DEV Community: Fernando Paladini

Build a Draft-First Medium Publishing Agent with MCP

Fernando Paladini — Sun, 13 Sep 2026 12:39:30 +0000

Publishing the same technical article on more than one platform sounds like a copy-and-paste task. In practice, the risky part is deciding what an AI agent is allowed to do with an authenticated browser session.

This tutorial builds a draft-first Medium workflow with publish-agents, an open-source TypeScript project by Fernando Paladini. The @paladini/medium-publisher-mcp@ package exposes Medium publishing operations through the Model Context Protocol, while keeping login, import, review, and live publication as separate decisions.

TL;DR

Install the stable v0.2.3 package, log in once, register its stdio MCP server, and ask your MCP client to import a public DEV.to article with publish: false. The agent can prepare and inspect a draft, but you retain approval for browser authentication, formatting changes, and publication.

What you will build

The resulting flow has four boundaries:

A public DEV.to article provides the source Markdown.
The local MCP server exposes publishing tools to an AI client.
Patchright uses a saved browser session to work in Medium.
A human reviews the real editor before any live publication.

MCP standardizes how a host connects to tools, but it does not make a tool safe by itself. The protocol documentation describes tools as capabilities that need consent and careful authorization. That is why this example uses a draft as the default outcome.

Prerequisites

You need:

Node.js 20 or newer.
An MCP-compatible client such as Cursor or Claude Code.
A Medium account that can create stories.
A published DEV.to article with a public URL.
Permission to install the bundled Chromium browser locally.

The tested release reference is v0.2.3. The package declares @paladini/medium-publisher-mcp version 0.2.3, requires Node.js >=20, uses Patchright, and is licensed under MIT.

Install the stable package

The shortest path installs the published npm package:

npm install -g @paladini/medium-publisher-mcp

The package exposes two commands: medium-publisher for the CLI and medium-publisher-mcp for the MCP server. Its post-install script requests the Patchright Chromium browser. If your package manager skipped that step, follow the Patchright installation documentation before trying browser automation.

You can verify that the CLI is on your PATH without logging in:

medium-publisher --help

If you prefer a source checkout, the stable repository documents this equivalent path:

git clone https://github.com/paladini/publish-agents.git
cd publish-agents
git checkout v0.2.3
npm install
npm run build -w @paladini/medium-publisher-mcp
npm link -w @paladini/medium-publisher-mcp

Create the local browser session

medium-publisher login

The documented Windows default is %LOCALAPPDATA%\\medium-publisher\\storageState.json. The package also supports MEDIUM_STATE_PATH and MEDIUM_PUBLISHER_HOME when you need a different local location.

Check the session in structured output:

medium-publisher session-check --json

Treat storageState.json like a credential store. Do not commit it, attach it to an issue, or place it in a CI artifact. A local browser profile can contain cookies that grant access to your Medium account.

Register the MCP server

The server uses stdio. A minimal MCP configuration is:

{
  "mcpServers": {
    "medium-publisher": {
      "command": "medium-publisher-mcp"
    }
  }
}

The repository includes client-specific setup notes for Cursor and Claude Code. After registering the server, restart or reload the client so it discovers the tools.

The package exposes seven tools in the documented release. The important ones for this workflow are medium_session_check, medium_publish_from_devto, medium_extract, medium_fix_draft, and medium_open_draft.

Import a DEV.to article as a draft

Ask the MCP client to call the server with a public article URL and an explicit non-publishing instruction:

{
  "devto_url": "https://dev.to/your-name/your-tutorial",
  "publish": false
}

This maps to the medium_publish_from_devto tool. The package fetches the published DEV.to representation, opens Medium's official /p/import route, waits for the editor to save, and returns JSON containing a Medium URL plus details such as title, subtitle, topics, and hero-image detection.

The false value is the critical control. It asks the pipeline to stop at a draft. Do not treat a successful tool response as proof that the article is ready for live publication. Open the returned editor URL and inspect it.

Review the actual editor

The source Markdown is the ground truth, but the Medium editor is the thing readers will see. Check:

The title and subtitle match the source.
Headings are rendered as headings rather than literal Markdown.
Each code example remains one code block with readable content.
Lists, links, and paragraphs keep their order.
Topics describe the article without adding unsupported claims.
No secret, private URL, or unexpected text crossed the import boundary.

The package's extraction command reports a structured outline and formatting flags:

medium-publisher extract --url "https://medium.com/p/your-draft/edit" --json

Pay special attention to content after the first code block. A malformed import can make later paragraphs look like code, which is easy to miss during a quick visual scan.

Apply a targeted correction

If extraction identifies a known issue, create a small actions file and apply only the required fixes:

[
  { "type": "removeEmptyCodeBlocks" },
  { "type": "mergeAdjacentCodeBlocks" },
  { "type": "promoteDemoteHeading", "blockIndex": 4, "level": 2 }
]

Run the correction against the same draft:

medium-publisher fix-draft --url "https://medium.com/p/your-draft/edit" --actions-file fixes.json --json

Then extract again and compare the affected blocks with the DEV.to source. Do not repeatedly apply actions when the editor structure has changed. A selector or block index that was correct for one draft can be wrong after an import or a Medium UI change.

Verify success before publishing

A useful verification record contains:

The source DEV.to URL.
The returned Medium draft URL.
The extraction result before any fix.
The actions file, if a fix was needed.
The extraction result after the fix.
A human check of title, code, links, metadata, and sensitive data.

Only after those checks should you decide whether to use a live publication option. The project also provides a CLI path with --publish, but this tutorial deliberately does not include it in the working command. Keeping the approval step outside the default agent request makes accidental publication less likely.

Why this design works

The workflow separates three kinds of state that are often conflated:

Source state: the published DEV.to Markdown.
Review state: the imported Medium draft and its extracted blocks.
Public state: the final Medium story after an explicit publication action.

That separation makes failures diagnosable. If the import is wrong, you can fix or discard the draft without changing the source. If the session expires, you can log in again without changing the article. If Medium changes its UI, you can stop at review instead of trusting an unattended browser run.

Failure modes and security boundaries

The session is missing or expired

The CLI documents exit code 3 for a missing or expired session. Run medium-publisher login again. Two-factor authentication or a bot challenge may require headed interaction.

The import does not complete

The DEV.to URL must be public. Check it in a private browser window and confirm that its public API representation contains the article body. An authenticated or unpublished source is not a reliable import input.

Medium selectors stop matching

Medium's interface can change. The repository specifically targets a contenteditable import field rather than assuming the first visible HTML input is the article URL field. If the workflow behaves unexpectedly, inspect the draft manually and report the reproducible case instead of publishing.

Sensitive data appears in the draft

Stop immediately. Do not publish the draft. Remove it through Medium's controls as appropriate, inspect the local browser-state directory, and rotate any credential that may have been exposed. The project's security check can flag secret-like values and unexpected short links, but it cannot replace human review.

FAQ

Does MCP publish automatically?

MCP only provides the connection between the client and the server. The server's publication capabilities still require authorization. Use publish: false for the draft-first workflow.

Do I need a Medium API key?

No. The documented package uses browser automation and a saved login session because it does not depend on a stable public Medium write API.

Can I use a personal blog instead of DEV.to?

The package supports importing public URLs generally, but the DEV.to pipeline can compare the imported result with DEV.to source Markdown. That comparison is the most useful part of this tutorial's verification loop.

Is the workflow production-proof?

No. Browser UI changes, account challenges, content-specific formatting, and authentication failures remain possible. The project reduces risk with extraction, targeted fixes, security checks, and draft-first behavior; it does not guarantee a successful unattended publication.

AI assistance disclosure

AI assistance was used to organize and edit this tutorial. The release, commands, MCP configuration, session paths, limitations, and security boundaries were checked against the public publish-agents repository at v0.2.3, its package documentation, and the current MCP specification.

Takeaway

An MCP publishing agent is most useful when it prepares reviewable state instead of silently crossing the publication boundary. Install a pinned release, save the browser session locally, import with publish: false, compare the Medium editor with the source, and keep live publication explicit.

What is the most valuable approval checkpoint in your own agent-assisted publishing workflow: authentication, content review, metadata review, or the final publish action?

Sync AI Guidance Across Repositories with a Reviewable GitHub Action

Fernando Paladini — Sat, 12 Sep 2026 12:36:29 +0000

Teams often standardize how they work with AI coding tools by adding files such as AGENTS.md, CLAUDE.md, Copilot instructions, prompt templates, and editor rules to every repository. The first copy is easy. Keeping those files aligned across dozens of repositories is where the process becomes fragile.

team-ai-sync is an open-source GitHub Action that treats shared guidance as source-controlled input. It copies selected files or directories into target repositories, creates a sync branch, and opens or updates pull requests for review. It also exposes a dry-run mode so you can inspect the intended changes before the action pushes anything.

This tutorial builds the smallest useful GitHub setup, explains the configuration that controls it, and shows where the tool's safety boundary ends.

TL;DR

Keep shared AI guidance in one source repository.
Configure target repositories and paths in sync-config.json.
Run paladini/team-ai-sync@v1 from GitHub Actions.
Start with dry-run: true.
Review the generated pull requests before merging them.

The stable action is documented in the v1 repository README, and the project is licensed under MIT.

Prerequisites

You need:

A GitHub source repository containing the shared files.
One or more target repositories that the token can read and write.
A fine-grained personal access token or GitHub App installation token.
Permission to create files, branches, and pull requests in the targets.

The action itself runs on Node 24 through its GitHub Action metadata. Your source repository workflow can use the standard ubuntu-latest runner.

For GitHub targets, the project documents Contents: Read and write, Pull requests: Read and write, and Metadata: Read. If you use pull request labels, it also documents Issues: Read and write. Store the token as a repository secret. Do not put it in sync-config.json or commit it to the repository.

1. Create the shared files

Use a source repository as the place where the team reviews shared guidance. A small example might look like this:

AGENTS.md
CLAUDE.md
.editorconfig
.github/
└── instructions/
    ├── code-review.md
    └── security.md

The action can sync individual files, whole directories, or both. Keep the source set intentionally narrow. Repository-specific secrets, credentials, local machine settings, and files containing personal data do not belong in a shared guidance bundle.

2. Add `sync-config.json`

Create this file in the source repository:

{
  "targetRepositories": [
    "your-org/api-service",
    "your-org/web-app"
  ],
  "syncMode": "overwrite",
  "deleteOrphans": false,
  "files": ["AGENTS.md", "CLAUDE.md", ".editorconfig"],
  "directories": [".github/instructions"],
  "exclude": [],
  "prOptions": {
    "title": "chore: sync team AI assets",
    "body": "Synced from {{sourceRepo}} at {{sourceCommit}}.",
    "commitMessage": "chore(ai-assets): sync team assets",
    "branch": "chore/team-ai-sync",
    "labels": ["automation", "chore"],
    "userReviewers": [],
    "teamReviewers": []
  }
}

targetRepositories is processed one repository at a time. files names exact repository-relative files. directories are copied recursively. exclude can remove specific paths or glob patterns from either input.

The default syncMode is overwrite, which replaces configured target files with the source version. Use skip when a file should be added only if it does not already exist. deleteOrphans is false by default. When enabled, deletion is limited to files inside configured synced directories, but it is still worth testing with a dry run first.

The placeholders in prOptions.body are replaced with the source repository and source commit from the workflow context. The generated branch, commit, pull request title, labels, and reviewers are also configured here.

For every configured source path, the project validates that the path exists and is a file or directory of the expected type before it processes targets.

3. Add the GitHub workflow

Create .github/workflows/sync-ai-assets.yml:

name: Sync AI Assets

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: paladini/team-ai-sync@v1
        with:
          github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
          config-path: sync-config.json
          dry-run: true

Create the TEAM_SYNC_ADMIN_PAT secret in the source repository. The workflow's GITHUB_TOKEN only needs to read the source checkout. The separate github-token input is used for target repository operations.

The v1 tag is the stable action reference documented by the project. If your organization requires immutable references, resolve the tag to a commit and apply your own pinning policy.

4. Verify the dry run

Push the configuration and workflow, or start the workflow through workflow_dispatch. With dry-run: true, the action validates the configuration, clones target repositories into temporary worktrees, copies the selected paths, and reports whether changes would be made. It does not push branches or create pull requests.

Check the run for three things:

Every target was reachable with the configured token.
The changed paths are limited to the files and directories you intended.
The output identifies failures per target instead of hiding them behind one aggregate result.

When the dry run is correct, remove dry-run: true or set it to false. The real workflow creates or resets the configured sync branch, commits only when there are changes, pushes that branch, and creates or updates one pull request per changed target.

Expected result

After a real run, each changed target should have a review request from the configured sync branch. The target owner can inspect the diff, request changes, and merge it through the repository's normal controls.

The action does not merge pull requests, approve them, bypass branch protection, or change target repository settings. That is the important operational distinction: synchronization is automated, while acceptance remains a repository-owner decision.

Why this works better than manual copying

The source repository becomes the review boundary for shared guidance. A change to a common instruction file is made once, tested once, and distributed as an ordinary pull request diff. Each target retains its own history and can reject or delay the update.

The configuration also makes scope explicit. Instead of granting a workflow permission to rewrite arbitrary paths, it names the files and directories that are eligible for synchronization. The implementation rejects absolute paths, .. traversal, .git paths, and values that resolve outside the repository root.

The project supports GitHub Actions, a GitLab CI/CD Component, and a Bitbucket Pipe. The configuration shape is similar, but the supported operating model is platform-specific. A GitHub workflow should target GitHub repositories rather than silently mixing platforms.

Failure modes and limitations

The token can reach too much

The action can clone targets, push branches, create pull requests, apply labels, and request reviewers. Use a fine-grained token or GitHub App installation with the smallest target set that supports the rollout. A path validator cannot compensate for an overpowered credential.

`deleteOrphans` can remove synced files

When deleteOrphans is enabled, files removed from a configured source directory can be removed from the corresponding target directory. Keep it disabled during the pilot, then enable it only with a reviewed dry-run diff.

Shared guidance is not automatically correct

The action distributes files; it does not decide whether an instruction is appropriate for every repository. Keep target-specific rules out of the shared bundle, and review changes for tool compatibility, scope, and unintended policy conflicts.

It does not merge the result

Generated pull requests still need review and merge. That is deliberate. If your process requires approvals, status checks, or security review, configure those controls in the target repositories.

FAQ

Can I sync directories such as `.cursor/rules`?

Yes. Add the directory to directories and keep the path repository-relative. The project documents .cursor/rules/**, .github/instructions/**, and .github/prompts/** as common use cases.

Can I preview changes without creating a pull request?

Yes. Set dry-run: true. The dry run validates and simulates the sync without pushing branches or opening pull requests.

Does it support files outside GitHub?

The project includes packages for GitLab and Bitbucket, but each package is intended for repositories hosted on its own platform. Use the package matching the target platform.

Where should secrets go?

Do not sync secrets, private keys, credentials, or machine-specific configuration. Store the action token in the source repository's secret store and keep the synchronized bundle limited to reviewable guidance and settings.

AI assistance disclosure

AI assistance was used to organize and edit this tutorial. The commands, configuration fields, security boundaries, stable action reference, and verification results were checked against the public paladini/team-ai-sync repository at the v1 tag and a clean checkout of that tag.

Takeaway

If your team maintains AI guidance in more than one repository, make the source explicit and distribute it through reviewable changes. Start with a small target set, run dry-run: true, inspect the paths and permissions, and expand only after the pull request workflow is predictable.

What is the first shared file your team would synchronize: AGENTS.md, editor rules, prompt templates, or something else?

Add 36 Local Developer Utilities to Cursor with an MCP Plugin

Fernando Paladini — Fri, 11 Sep 2026 23:56:21 +0000

If you repeatedly leave Cursor to generate a UUID, decode a JWT, calculate a CIDR range, or format JSON, the problem is not the individual command. The problem is the missing tool boundary inside your coding workflow.

The DevUtils MCP Plugin packages a local MCP server for Cursor and Claude Code. It exposes 36 small developer utilities for hashing, encoding, JSON, JWTs, UUIDs, text, and network calculations. The plugin does not require an API key, and its configuration starts the server with npx on your own machine.

This tutorial shows the smallest useful path: install the plugin, inspect the configuration, enable the MCP server, and verify the result with a few safe requests.

TL;DR

Install DevUtils MCP from Cursor's Customize page, enable the devutils server, then ask your agent to generate a UUID or validate JSON. The plugin wrapper is public and MIT licensed. The underlying devutils-mcp-server is currently version 1.1.0 on npm and requires Node.js 18 or newer.

Prerequisites

You need:

Cursor with plugin and MCP support.
Node.js 18 or newer available as node and npx in your PATH.
Permission to download the public npm package the first time the server starts.

The plugin repository itself is public and MIT licensed. The repository's current plugin manifests declare version 1.0.7. The server is a separate package, so keep those two versions distinct.

Install the plugin in Cursor

Cursor documents plugins as bundles that can include MCP servers, rules, skills, agents, commands, and hooks. Its current installation flow is:

Open Cursor's Customize page.
Find the plugin in the marketplace or use the community plugin flow.
Search for DevUtils MCP.
Choose Install and select the scope you want.
Enable the devutils MCP server in the installed plugin.

The Cursor plugin documentation describes the marketplace and installation flow. If the plugin is not listed in your account yet, the repository README documents the direct Add from GitHub route with paladini/devutils-cursor-plugin.

After installation, reload Cursor if the MCP server does not appear immediately. Then open the MCP section in Customize and confirm that devutils is enabled.

Understand the one-file configuration

The repository's current mcp.json contains this exact server definition:

{
  "mcpServers": {
    "devutils": {
      "command": "npx",
      "args": ["-y", "devutils-mcp-server"]
    }
  }
}

There are two useful details here. First, npx -y can install the named package when it is not already available locally. Second, the server is a stdio process. Cursor starts it and communicates with it through the MCP protocol; you do not need to expose an HTTP port or copy an API key into a configuration file.

The MCP server repository is the primary source for the tool catalog and server implementation. The plugin is a distribution wrapper that makes the configuration discoverable from Cursor and Claude Code.

Try the minimal workflow

Once the server is enabled, ask your agent for a small operation whose input is not sensitive. For example:

Generate a UUID v4 with the DevUtils MCP server.

Then try a deterministic transformation:

Pretty-print this JSON and validate it with DevUtils:
{"project":"demo","enabled":true}

You can also ask for a calculation:

Calculate the network details for 10.0.0.0/24 with DevUtils.

The expected result is an agent response backed by a named DevUtils tool. The exact UUID value changes on every generation. For the JSON request, you should see formatted JSON and a valid result. For the CIDR request, expect the network address, broadcast address, host range, and host count.

The server also exposes tools for SHA hashing, Base64 and hexadecimal conversion, JWT decoding, date and timestamp conversion, regex checks, text statistics, URL encoding, and other small operations. The available-tools section in the server README is the authoritative catalog, so check it before writing prompts that depend on a particular name.

Verify the process without Cursor

The plugin is optional. Any MCP client that accepts a stdio server can use the same package directly:

npx -y devutils-mcp-server

This command is a long-running server process, not a traditional command that prints a result and exits. A successful startup keeps the process attached to stdio. Stop it with Ctrl+C when testing manually.

In my validation of the current package, npm view devutils-mcp-server version license engines returned version 1.1.0, MIT licensing, and the Node.js engine requirement >=18. Starting the package with npx -y devutils-mcp-server --help reached the server and reported DevUtils MCP Server running on stdio; because it is a server, the process needed to be stopped after startup. That verifies launch, not every individual tool.

Why this setup works

The plugin separates distribution from execution. The repository contributes manifests, the MCP configuration, documentation, and privacy and security policies. The npm package contributes the executable server and tool handlers. Cursor only needs to understand the MCP entry in mcp.json.

That separation also keeps the example portable. Claude Code can install the plugin with its marketplace command, while another MCP client can run the npm package directly. The configuration remains a small, reviewable JSON file rather than a collection of copied shell commands.

Failure modes and boundaries

If the server does not appear in Cursor, check the plugin scope, reload Cursor, and confirm that npx resolves in the environment used by the editor. If startup fails, run node --version and npx --version in a terminal, then check whether npm can reach the registry.

If a request fails, verify the tool exists in the current server README. The plugin repository says 36 utilities, but the server package is independently versioned and can change. Do not assume a tool name from an old prompt or screenshot.

Local execution is not the same as a security guarantee. Inputs are processed by the local server according to the implementation, but npx still downloads a package from npm on first use. Review the package, lock down your normal npm trust controls, and avoid sending production secrets, private tokens, or customer data to any tool until you have reviewed its source and behavior. JWT decoding is not JWT verification, and hashing does not make a sensitive value safe to disclose.

The plugin does not provide a cloud API, authentication layer, or remote dashboard. It also does not replace a secrets manager, a security scanner, or a full network diagnostic system. Its value is narrow: convenient, repeatable local utilities inside an agent workflow.

FAQ

Does it need an API key?

No API key is required by the plugin or the documented server configuration.

Does it work outside Cursor?

Yes. The plugin README documents direct server usage for other MCP clients, including Claude Code, VS Code, Windsurf, and Docker references.

Does local mean no network activity?

No. The tool operations run in the local server process, but npx may download devutils-mcp-server from npm when it is first run.

Can it verify a JWT signature?

The documented JWT utility decodes and validates token structure and expiration-related information. Treat decoding as inspection, not cryptographic signature verification.

Takeaway

A useful MCP integration does not need to be a large platform. A public manifest, a one-file stdio configuration, and small deterministic tools are enough to remove repetitive context switching from an agent workflow. Install DevUtils when those utilities belong inside your local development loop, and keep the server's version, source, and input boundaries visible to the team.

What small local utility would save you the most context switching inside your coding agent: JSON validation, token inspection, hashing, or something else?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Repository files, package metadata, documented commands, and the startup behavior described here were checked against the current public sources before publication.

Download Authorized Circle Course Videos with Python and Playwright

Fernando Paladini — Thu, 10 Sep 2026 12:39:40 +0000

If you have permission to watch a Circle course but your connection is unreliable, saving it for later is harder than it sounds. The useful data is behind a browser session, course pages can contain many lessons, and a downloader should not turn authentication into a pile of copied cookies.

This tutorial shows a local workflow with Circle Course Downloader. It opens a dedicated Chromium profile for you to sign in normally, discovers video URLs from pages you can already access, and delegates the media transfer to yt-dlp.

The important boundary is authorization: use this only for content you are allowed to view and download. The project is unofficial and does not bypass DRM, paywalls, two-factor authentication, captchas, or access controls.

TL;DR

Install version 0.1.4 from PyPI, install the Chromium runtime, and run a dry run against a course URL:

py -m pip install circle-course-downloader
py -m playwright install chromium
circle-course-downloader download "https://your-community.example.com/c/course-slug" --dry-run

On the first run, a visible Chromium window lets you authenticate. The tool stores the session in its own local profile, discovers lessons, and prints the yt-dlp commands without downloading media. Remove --dry-run only after checking the result and confirming your rights to save the content.

Prerequisites

You need Python 3.11 or newer, an account authorized for the Circle community and specific content, Chromium installed through Playwright, and enough local disk space for the media.

The package is MIT licensed and currently early-stage software. Version 0.1.4 is available on PyPI and the source is maintained in the public GitHub repository.

Create a virtual environment when you want the CLI isolated from other Python tools:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install circle-course-downloader
python -m playwright install chromium

Start with a dry run

Use download for a full course page. Replace the example hostname and slug with a URL from your own community:

circle-course-downloader download "https://your-community.example.com/c/course-slug" --dry-run

The first run opens a dedicated Chromium profile. Sign in in that window, return to the terminal, and press Enter. This is deliberately browser-first. You do not paste a password into the terminal, export cookies from your default browser, or place a token in a command argument.

After authentication, the downloader visits the course page, finds lesson links, inspects each lesson for supported video providers, and prints the commands it would use. The supported list includes Circle HLS, direct video URLs, YouTube, Vimeo, Wistia, Loom, Mux, and Cloudflare Stream.

The dry run is a decision point. Review the discovered lesson names and URLs. If the page includes material you are not authorized to download, stop there or narrow the operation according to the project capabilities and service rules.

For a single community post or event page with one embedded video, use the separate command:

circle-course-downloader download-standalone "https://your-community.example.com/c/space-slug/post-slug" --dry-run

The commands are not interchangeable. download expects a course structure with sections and lessons. download-standalone targets one page with one embedded video.

Download after checking the plan

When the dry-run output matches your intended scope, run the same command without --dry-run:

circle-course-downloader download "https://your-community.example.com/c/course-slug"

By default, media and manifests go under downloads/. Use --output-dir for a dedicated destination:

circle-course-downloader download "https://your-community.example.com/c/course-slug" --output-dir "./authorized-course-export"

The downloader uses yt-dlp with resume support and MP4 merge output. This helps with long courses and interrupted connections, but it does not guarantee that every provider or stream will work forever. Provider changes, expired signed URLs, unavailable lessons, and codec issues can still affect individual downloads.

The yt-dlp documentation describes its output and continuation behavior. That downstream tool receives URLs discovered from the authorized browser session, so protect those URLs like credentials.

Understand the local files

The default layout is easy to inspect:

.auth/session-browser-profile/
.auth/session.json
downloads/manifest.json
downloads/manifest.csv
downloads/01 - Lesson title.mp4

The manifest records what discovery found. Treat it as an audit artifact, not disposable noise. It can contain signed media URLs, so do not publish or commit it.

The session files are even more sensitive. Playwright's authentication documentation explains that saved browser state can contain cookies, local storage, and other credentials that may impersonate an account. Keep .auth/ local and add it to .gitignore in any workspace where you use the tool.

This design follows Playwright's storage-state pattern: authenticate once in a controlled browser context and reuse that state later. It is safer than copying cookies from a personal browser, but it is not a security boundary. Anyone who obtains the stored state may be able to act as you until it expires or is revoked.

Useful options

Both commands accept the same operational options:

circle-course-downloader download "https://your-community.example.com/c/course-slug" --output-dir "./downloads" --session "./.auth/session.json" --headless

Use --session to choose a different exported session location. The browser profile is stored next to it. Use --force-login when the existing session is stale and you want a fresh visible login. Use --headless only after a saved browser profile exists. A first login requires a visible browser window.

The CLI exposes the exact options installed on your machine:

circle-course-downloader download --help
circle-course-downloader download-standalone --help

Verify the installation locally

You can verify the installed CLI without logging into a community:

circle-course-downloader --help
circle-course-downloader download --help
circle-course-downloader download-standalone --help

For a source checkout, the repository's development checks include tests, Python compilation, wheel building, and package metadata validation. At the current v0.1.4 release commit, those checks completed successfully in a clean checkout: 17 tests passed, compileall passed, the package build produced both sdist and wheel, and twine check passed for both artifacts.

Those results validate the package and parser logic. They do not prove that a particular Circle community, lesson, provider, or account session will work today. The meaningful end-to-end check for your account is a small authorized dry run followed by one or two downloads that you can inspect.

Failure modes and limits

If Chromium does not start, install the browser runtime with python -m playwright install chromium and check that the active Python environment is the one running the CLI.

If the browser opens but discovery returns no lessons, confirm that the URL is a full course page and that the signed-in account can see the lessons in the browser. For one standalone post, use download-standalone instead.

If a session stops working, use --force-login. Do not work around the problem by copying cookies or tokens from another browser. If a provider URL has expired, rerun discovery instead of sharing the old signed URL.

The tool does not defeat access controls. It cannot make unavailable content available, and a successful browser login is not proof that downloading is contractually or legally permitted. Check the course license, community terms, and content owner's instructions.

FAQ

Does this upload my course to an API?

The project runs the browser and downloader locally and does not require a hosted AI service. It still connects to the community and media providers required to authenticate, discover pages, and transfer authorized files.

Can I reuse my normal Chrome profile?

The documented workflow uses a dedicated Chromium profile. Keep it separate. This avoids exposing unrelated browser cookies and makes the session files easier to identify and protect.

Can I use it for any video URL?

No. It is designed around Circle course and community pages and the providers its extractors recognize. It is not a general-purpose access-control bypass.

Why run `--dry-run` first?

It makes the scope visible before media is written. You can inspect discovery results, catch a wrong URL, and review the generated commands before accepting the external content transfer.

Takeaway

The useful pattern is a controlled workflow: authenticate in a dedicated browser, discover only what the account can already access, inspect the plan, download locally, and protect the session and manifest files.

Circle Course Downloader packages that workflow behind two small commands. Start with --dry-run, test a narrow authorized scope, and treat the current 0.1.4 release as early-stage software whose provider support can change.

Have you found a reliable way to audit and expire local browser sessions for authorized offline course backups?

AI assistance disclosure

AI assistance was used to organize and edit this tutorial. The commands, package metadata, repository behavior, test results, security boundaries, and limitations were checked against the public project sources and local validation runs described above.

Govern AI-Assisted Specs in Git with SpecGov

Fernando Paladini — Wed, 09 Sep 2026 12:37:13 +0000

AI coding agents can produce code faster than a team can review the documents that are supposed to govern that code. A repository may contain requirements, designs, tasks, and verification notes, while Git itself does not tell you whether a change still has a complete chain back to those artifacts.

SpecGov is an open-source TypeScript CLI and GitHub Action for that specific gap. It discovers common spec-driven workflows, normalizes their files into an artifact graph, and reports missing relationships or code changes that bypass explicit mappings. The useful part is its boundary: it checks repository structure and declared relationships, not whether an AI claim is true.

In this tutorial, you will build SpecGov from its public repository, run a local check, inspect the graph, add a domain mapping, and wire the result into a pull request workflow.

TL;DR

SpecGov gives a repository a deterministic governance check for durable development artifacts. It supports GitHub Spec Kit, OpenSpec, Kiro, and configurable Generic/TLC layouts. It runs locally without an account, API key, upload, or network call after installation.

The current repository documents version 1.0.0-rc.2 on the main branch. At the time of writing, that release candidate was not available from npm, so the commands below use a checkout and local build. Treat this as a current-source tutorial, not proof of a stable package release.

Prerequisites

Git
Node.js 20 or newer
A repository containing specifications, plans, tasks, or other durable development artifacts
A shell with permission to install dependencies and run Node.js

The project is released under the MIT license. Its README and package metadata identify Fernando Paladini as the author and paladini/specgov as the source repository.

Build and run the minimal path

Clone the repository and build the CLI:

git clone https://github.com/paladini/specgov.git
cd specgov
npm ci
npm run build

Run the generated CLI against the checkout itself:

node dist/cli.js check

The repository currently reports an advisory pass with the Generic framework, two change sets, seven artifacts, and zero findings. Your output will differ if you run it against another repository or a newer commit. The important result is the shape of the report: detected frameworks, change sets, artifacts, findings, evidence, and remediation details.

You can inspect the normalized graph as Markdown:

node dist/cli.js graph --format markdown

The graph lists artifact IDs, paths, roles, and relationships such as derives_from and verifies. This is more useful than a directory listing because it makes the relationships that governance depends on visible and reviewable.

Finally, preview the configuration SpecGov would create from detected workflows:

node dist/cli.js init --dry-run

The command prints a specgov/v1 manifest without changing the repository. That makes it a safe first step when you are inheriting an existing spec layout.

Add an explicit domain mapping

Autodetection is useful for common layouts, but path-sensitive governance should be explicit. Add a .specgov.yml file when a code area must be connected to particular artifacts:

schema: specgov/v1
mode: advisory
frameworks: auto

domains:
  - id: authentication
    code:
      - "src/auth/**"
    artifacts:
      - "specs/auth/**"
      - ".kiro/specs/auth/**"

policies:
  require_complete_chain: true
  require_change_artifact_for_code: true
  require_verification_evidence: false
  stale_after_days: 90

The domains block says which artifacts govern which code. The policy flags then define the minimum structural chain. A changed specification in an unrelated directory does not satisfy an explicit domain, which prevents a generic document from hiding a missing authentication-specific change.

Run the check again:

node dist/cli.js check

Start with mode: advisory while you learn the repository's actual shape. Once the findings are understood, strict mode can make policy findings fail the command. The project documents exit code 1 for strict policy failures and exit code 2 for configuration or runtime errors.

Enforce the result in GitHub Actions

SpecGov also ships a GitHub Action. The documented workflow checks out the full history and compares the pull request base and head revisions:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
- uses: paladini/specgov@v1
  with:
    mode: strict
    base-ref: ${{ github.event.pull_request.base.sha }}
    head-ref: ${{ github.event.pull_request.head.sha }}

The Action writes a Markdown summary and exposes status, report JSON, graph JSON, detected frameworks, and finding count. Full history matters because the comparison needs both revisions. The v1 Action reference is separate from the current npm-style package version shown in package.json, so check the project's release guidance before pinning a production workflow.

Why this works

SpecGov separates three questions that are often mixed together:

Which artifact workflows exist in this repository?
Are the declared files and relationships structurally complete?
Is the content semantically correct and truthful?

The first two are deterministic enough for a local command and a pull request check. SpecGov can prove that files, states, relationships, and explicit path mappings satisfy configured structural policy. It cannot prove that a requirement is well designed, that a test really covers a behavior, or that a declared AI producer actually created a file. Optional semantic auditors can add review signals, but they do not change that boundary.

That limitation is a feature for CI. A governance check should report evidence that a machine can reproduce, not turn an unverified declaration into a security guarantee.

Common failure modes

The documented `npx` command cannot resolve

The README shows npx specgov check, but the checked npm registry query did not find specgov@1.0.0-rc.2. Use the checkout workflow above until the package is published, or confirm the exact version in the registry before sharing an npx command.

The check passes but the change is still wrong

That is expected. A pass means the structural policy was satisfied. It does not validate business logic, semantic quality, authorship, or the correctness of an external claim. Keep normal code review, tests, and security review in the workflow.

A strict check fails unexpectedly

Inspect the report and graph first. Look for an incomplete artifact chain, a missing domain mapping, a stale artifact, or a base/head reference that is not available in the checkout. Run advisory mode locally to understand the findings, then make the smallest explicit mapping that represents the intended workflow.

Old manifests stop working

SpecGov v1 is an intentional break from the v0.1 contract. The upgrade guide says that old version, artifacts, mappings, and rules fields and the old scan, check-pr, trace, and drift commands are unsupported. Use specgov init --dry-run, convert trusted mappings into domains, and replace old PR checks with specgov check --base-ref ... --head-ref ....

FAQ

Does SpecGov upload repository content?

The project documents local and deterministic behavior by default, with no account, API key, upload, or network call. Verify the version and configuration you deploy, and review the repository's security policy for your environment.

Does it replace a spec-authoring framework?

No. It governs artifacts created by workflows such as GitHub Spec Kit, OpenSpec, Kiro, or a Generic/TLC layout. It is a governance layer, not another authoring system.

Can I use it without GitHub Actions?

Yes. The CLI is the primary local path. The Action is an optional enforcement boundary for pull requests.

Takeaway

The practical value of SpecGov is not that it makes AI-assisted development automatically correct. It makes the repository's declared development chain inspectable: code, artifacts, relationships, and policy become evidence that a local command and CI can reproduce.

If you try this on a real repository, begin with init --dry-run, review the graph, and keep advisory mode until the findings match your team's intended workflow. Then decide which structural rules are strong enough to block a pull request.

This tutorial was prepared with AI assistance. The repository documentation, package metadata, current configuration example, checkout build, tests, lint, typecheck, format check, audit, and CLI smoke commands were checked against the public project state at publication time.

What artifact relationship would you want a pull request check to prove before code could merge?

Back Up GitHub Repositories to GitLab with Python

Fernando Paladini — Tue, 08 Sep 2026 02:16:29 +0000

Keeping every repository on one hosting platform creates a single point of failure for your source code. A second copy helps, but a backup script that treats every repository as public can create a much worse problem: accidental exposure.

This tutorial walks through backup-github-to-gitlab, an open-source Python tool that lists a GitHub user's repositories, creates matching GitLab projects, and mirrors branches and tags over SSH. The workflow defaults private when it cannot determine visibility, supports a dry run, and can be run again to push incremental updates.

TL;DR

The smallest useful workflow is:

Install Python dependencies and Git.
Create a YAML configuration and put API tokens in environment variables.
Run python backup.py --dry-run to inspect the plan.
Run python backup.py after checking the proposed visibility.

The tool is a repository backup, not a complete disaster-recovery system. It does not transfer Git LFS objects, organization repositories, or wikis in its current version.

Prerequisites

You need Python 3.11 or newer, Git on your PATH, and SSH keys registered with both GitHub and GitLab. The project also expects a GitHub token with repo scope and a GitLab token with api scope. Those scopes are used by the API clients to list repositories and create GitLab projects.

The repository is MIT-licensed and the current source is available in backup-github-to-gitlab on GitHub. The dependency list includes PyGithub, python-gitlab, python-dotenv, Rich, and PyYAML.

Install the tool

Clone the project and install its dependencies:

git clone git@github.com:paladini/backup-github-to-gitlab.git
cd backup-github-to-gitlab
python -m pip install -r requirements.txt

The script exposes a normal command-line help screen. python backup.py --help shows options for dry runs, repository glob filters, verbose Git output, forks, archived repositories, and an alternate configuration path.

Configure credentials and usernames

Copy the checked-in configuration example to config.yaml and set the GitHub and GitLab usernames:

github:
  username: your-github-username

gitlab:
  username: your-gitlab-username
  url: https://gitlab.com

backup:
  include_forks: false
  include_archived: true
  temp_dir: ./tmp

Put the tokens in your process environment or in a local .env file that is not committed:

GITHUB_TOKEN=your-github-token
GITLAB_TOKEN=your-gitlab-token

The application loads .env at runtime. The tokens are not read from config.yaml, and the README states that they are not written to logs. Treat any token copied into a shell history, terminal recording, or issue as compromised and rotate it.

Preview the backup safely

Before making a GitLab project or pushing objects, run the dry-run mode:

python backup.py --dry-run

The runner still queries GitHub and checks whether each matching GitLab project exists, but it returns a dry_run result instead of creating projects, cloning repositories, or pushing Git data. A typical report distinguishes an existing project from a project that would be created, and shows whether the project would be public or private.

For a narrower preview, use a glob filter:

python backup.py --dry-run --filter "client-*"

This is useful for a first run against a small set of repositories. The default configuration skips forks and includes archived repositories. The command-line flags can override those choices when you intentionally want a different scope.

Run the mirror

After reviewing the dry-run output, execute the backup:

python backup.py

For each repository, the runner follows this sequence:

Ask GitHub for repositories owned by the configured user.
Check whether the matching GitLab project exists.
Create the GitLab project with the visibility reported by GitHub, or reuse its SSH URL.
Run git clone --mirror from the GitHub SSH URL.
Run git push --mirror from the temporary mirror to GitLab.
Remove the temporary clone, including read-only Git files on Windows.

The mirror flags matter. A normal working-tree clone is optimized for editing one branch. A mirror clone contains all refs, and a mirror push updates the destination refs to match the source. That makes the operation appropriate for a source backup, while also meaning that the destination should be dedicated to this mirror. Manual changes made directly in GitLab can be overwritten by a later run.

Why reruns are safe enough for routine backups

The tool checks for an existing project before creating one. On a later run it gets that project's SSH URL, creates a fresh temporary mirror, and pushes the current GitHub refs. This makes the process idempotent at the project level: rerunning it does not create duplicate GitLab projects.

It is not a versioned backup in the archival sense. If a branch or tag is removed from GitHub, git push --mirror can remove the corresponding ref in GitLab. If you need point-in-time recovery, add a separate retention policy such as dated bare-mirror snapshots or storage-level backups.

Visibility and security boundaries

Visibility is the most important safety property in this workflow. The GitHub client maps the API's private value into a repository record. The GitLab client creates a project as private when that value is true and as public otherwise. The README also documents a private-by-default policy when visibility cannot be determined, so verify the actual project settings before pushing sensitive code.

The tool uses SSH for Git transport and API tokens for metadata operations. That separates repository content transfer from API authentication, but it does not remove the need to protect either credential. Use a dedicated GitLab account or group when appropriate, review token scopes, and test the process with a non-sensitive repository first.

The dry run is a planning aid, not a permission boundary. It can show what the program intends to do, but it cannot prove that a token has the right permissions or that an SSH key can push. A small real run is the discriminating test.

Failure modes to expect

The configuration file is missing

The default path is config.yaml. Create it from config.example.yaml, or pass another file with --config. The validator reports missing usernames and missing GITHUB_TOKEN or GITLAB_TOKEN before the runner starts.

Git authentication fails

The API tokens do not authenticate the Git SSH connection. Confirm that ssh -T git@github.com and the equivalent GitLab SSH check work for the account that owns the destination projects. With --verbose, the tool exposes Git command output that can help isolate an SSH problem.

A GitLab project already contains unrelated data

The project intentionally pushes a full mirror. Do not point it at a destination that people edit independently. Create a dedicated project or confirm that replacing its refs is acceptable.

Rate limits or transient API errors occur

The GitHub client waits for a core API rate-limit reset. GitLab HTTP 429 responses are retried up to four times with a 60-second delay. A failure after those retries is reported for that repository, while the runner continues processing the list.

Limitations

The current README explicitly lists three limits:

Git LFS objects are not transferred by git clone --mirror.
Organization repositories are not included in version 1.
GitLab pull mirroring for private repositories requires GitLab Premium, and the planned GitHub Actions alternative is not implemented here.

Wikis are also listed as a future roadmap item. If any of these are part of your recovery objective, treat this tool as one layer of the backup plan and verify those assets separately.

FAQ

Does the tool copy private repositories as public?

The implementation maps GitHub visibility to the GitLab project. Private repositories are created as private. Still inspect the dry-run output and destination settings before using it for sensitive repositories.

Can I back up only one repository?

Yes. Use a matching glob, such as --filter "my-project", and run a dry run first.

Does it need a GitHub Actions workflow?

No. It runs locally and uses the GitHub and GitLab APIs plus SSH Git operations.

Is this a replacement for snapshots?

No. It keeps a GitLab mirror current. Add retention and independent storage if you need historical recovery after deletions or corruption.

Takeaway

backup-github-to-gitlab is a focused way to create a second Git hosting copy without writing custom API and Git orchestration code. Its strongest design choices are the dry-run mode, visibility-aware project creation, mirror refs, and cleanup of temporary clones. Start with one harmless repository, verify both API and SSH authentication, inspect the proposed visibility, and only then expand the filter.

What would you add first for your own backup policy: Git LFS support, organization repositories, or retention-aware snapshots?

Disclosure: AI assistance was used to organize this tutorial and review its wording. The commands, behavior, limitations, and project details were checked against the repository's current public README, source files, configuration example, dependency list, license, and public GitHub metadata.

Harness Score 1.6.4: Safer Scans, Broader CI, and Trustworthy Docs

Fernando Paladini — Sat, 05 Sep 2026 17:14:57 +0000

AI coding agents do not work in a vacuum. Their results depend on the context files, rules, skills, hooks, tests, CI pipelines, and safety controls that surround the model. That surrounding system is the harness: the part of an agentic workflow that a team can actually design, version, test, and improve.

Harness Score turns that idea into a deterministic repository audit. It checks 36 concrete signals across six dimensions, assigns a maturity level from L0 to L4, and shows the next gaps to close. It runs with zero LLM calls, zero network access during a scan, and zero runtime dependencies.

Since version 1.5.3, the project has gone through a focused release train. The goal was not to inflate the score or add flashy checks. It was to make the result safer to trust across large repositories, monorepos, self-hosted CI systems, and five documentation languages.

TL;DR

Harness Score can now:

audit the structural readiness of an AI coding harness across Cursor, Claude Code, Codex, Windsurf, Cline, Continue, OpenCode, Zed, and other supported conventions;
fail closed instead of presenting a partial filesystem walk as an authoritative score;
inspect complete, deeply nested repositories with a much larger safety fuse;
recognize CI configuration inside nested workspaces, Google Cloud Build directories, and Forgejo Actions;
produce terminal, JSON, Markdown, badge, diff, and GitHub Action outputs;
keep its check catalog, points, dimension totals, and maturity thresholds synchronized across English, Brazilian Portuguese, Spanish, Simplified Chinese, and Hindi.

The latest version is 1.6.4. You can run the default audit without installing it in your project:

npx --yes harness-score

What Harness Score is actually measuring

The harness engineering discussion is broader than any single tool. Birgitta Böckeler describes an outer harness that combines guidance with feedback sensors so agents can prevent mistakes and self-correct earlier. LangChain's anatomy of an agent harness similarly separates the model from the surrounding prompts, tools, permissions, state, and execution infrastructure.

Harness Score focuses that broad idea on evidence that can be found in a software repository. Its six dimensions are:

Context & Guides: whether the agent can understand the project and its conventions;
Skills & Commands: whether repeated procedures are packaged and discoverable;
Hooks & Guardrails: whether important behavior is enforced during agent execution;
Sensors & Feedback: whether tests, linting, types, formatting, and test files can check the work;
CI Feedback: whether those sensors run as part of the delivery workflow;
Hygiene & Safety: whether secrets, environment files, lockfiles, licenses, and MCP configuration are handled safely.

The result is not just a percentage. The maturity ladder distinguishes a repository that is merely documented from one that has feedback loops and enforced guardrails. Each failed check includes evidence and a remediation path in the complete check catalog.

Version 1.5.3: do not trust an incomplete scan

The most important change in 1.5.3 was a safety decision: an incomplete repository walk must not look like a complete evaluation.

Before this release, filesystem limits or unreadable paths could produce a partial view while still leaving a maturity result visible. Version 1.5.3 made incomplete repository and effective-scope walks fail closed. Terminal output, Markdown reports, badges, diffs, the CLI exit status, and the GitHub Action all learned the difference between an authoritative result and provisional diagnostics.

This matters because a high score based on only the easy-to-read part of a repository is worse than no score. It creates false confidence.

The same release improved native tool-root support. If a supported configuration directory was itself the scan root, Harness Score became better at recognizing Claude Code, Cursor, Codex, Windsurf, Cline, Continue, Gemini, Zed, OpenCode, and GitHub harness layouts. Hook configuration selection also became deterministic, with updated Claude Code event and handler validation and forward-compatible warnings for structurally valid future events.

Version 1.6.0: complete repository scans at real-world scale

Version 1.6.0 extended that fail-closed foundation. The production depth cap was removed, and the file-count safety fuse increased to 1,000,000 files.

That change is especially useful for monorepos and deeply nested workspaces. A CI workflow, rule, test suite, or harness artifact should not disappear from the evaluation simply because it lives farther down the tree than expected.

The scanner also began treating discovered paths that cannot be inspected and symlinks that escape the scan root as explicit incomplete-scan conditions. The important product behavior stayed the same: Harness Score can still explain what it found, but it will not pretend that a partial snapshot is an authoritative maturity verdict.

No check IDs, points, thresholds, or public APIs changed in 1.6.0. The release improved the reliability of the measurement rather than changing the ruler.

Version 1.6.1: CI inside nested workspaces now counts

Many repositories do not keep every CI file at the top level. A monorepo may contain independently deployed applications, each with its own Jenkinsfile, GitLab pipeline, Azure Pipelines configuration, CircleCI setup, or Bitbucket pipeline.

Version 1.6.1 made non-GitHub CI discovery work at any depth below the scan root. It also stabilized evidence ordering and removed duplicate evidence when matcher patterns overlap.

For users, the practical improvement is simple: you should not need to rearrange a legitimate workspace structure just to make the scanner understand that CI exists and runs tests or static checks.

This release was also a good example of open-source feedback improving the product. Thanks to Felipe Contratres for reporting the nested-workspace problem and contributing the initial fix, and to dbtorrico for identifying a guide-locale parity gap and suggesting translations.

Version 1.6.2: Google Cloud Build support

Version 1.6.2 added deterministic discovery for Google Cloud Build configurations under cloudbuild/ using .yml or .yaml files.

Those files can now contribute evidence to the CI pipeline, test execution, and lint/type-check checks. The scanner remains filesystem-only: it confirms that the configuration is present and contains the relevant commands, but it does not call Google Cloud or claim that a remote pipeline actually ran.

Thanks to Gabriel Caiana for reporting the gap and supplying a reproducible Cloud Build pipeline.

Version 1.6.3: Forgejo Actions support

Not every team hosts its repositories and automation on GitHub. Version 1.6.3 added support for Forgejo Actions workflows in .forgejo/workflows/.

That makes the CI dimension more useful for teams choosing a self-hosted, open-source forge. The same CI checks can recognize the workflow and its test and lint/type-check steps without adding a provider API, credentials, telemetry, or network behavior to the scanner.

Taken together, versions 1.6.1 through 1.6.3 move Harness Score closer to its intended position: the repository structure and working controls should matter more than the vendor logo on the pipeline.

Version 1.6.4: documentation that cannot silently drift

The scanner already had the correct weights, but the compact check table in the documentation had five stale values. Version 1.6.4 corrected them in every locale:

CI-03: 3 points;
CI-04: 3 points;
HYG-01: 2 points;
HYG-06: 2 points;
HYG-08: 3 points.

More importantly, the release expanded the synchronization tests. CI now verifies unique and complete table rows, the weights defined by the implementation, all six dimension totals, detailed catalog headings, the 108-point total, and the maturity thresholds across all five languages.

This patch did not change anyone's score. It aligned the public explanation with the implemented model and made the same class of drift fail CI in the future. The 1.6.4 release notes include the complete validation record.

Turn the score into a ratchet, not a one-time report

A local scan is the fastest way to understand the project, but the score becomes more useful when it is part of the engineering loop.

Save a machine-readable baseline:

npx --yes harness-score --json > harness-score.json

Compare a future scan against it:

npx --yes harness-score --diff harness-score.json

Or set a minimum maturity level in CI:

npx --yes harness-score --min-level 3

The GitHub Action can run the same audit on every push or pull request:

- uses: paladini/harness-score@v1
  with:
    min-level: '3'

For stricter supply-chain control, pin the Action to a full commit SHA. For a quick adoption path, the stable v1 tag follows compatible 1.x releases.

What the score does not prove

Harness Score is an objective measure of repository-level harness infrastructure, not a certification of final software quality.

It can verify that tests, linters, type checking, CI workflows, context files, hooks, and safety patterns exist and are structurally connected. It does not prove that the tests assert the right behavior, that an AGENTS.md is perfectly written, that a remote pipeline is healthy, or that an agent understood the product requirement.

Use it as a readiness map and an improvement backlog. Combine it with code review, runtime observability, product evaluation, security testing, and semantic checks appropriate to your system.

What is planned next

The public roadmap is a direction of travel, not a promise of dates or release numbers. The main planned areas are:

harness-score init: deterministically scaffold starter artifacts for high-value missing checks, turning diagnosis into an optional, reviewable first fix.
SARIF output: bring relevant findings into GitHub's code-scanning experience.
Larger real-world corpus studies: use evidence from public repositories to challenge and calibrate thresholds, weights, and missing checks, then publish the findings.
Broader ecosystem detection: recognize more test runners, linters, type checkers, and CI conventions as real repositories expose gaps.
More tool adapters: continue the multi-harness plugin plan beyond the current Cursor and Claude Code work, with lightweight integrations for Codex, OpenCode, Junie, Windsurf, Cline, Continue, and Zed before considering a heavier VS Code extension.

There are also narrower reliability improvements under discussion and community review, including generated environment directories that should not invalidate a scan and better parity when a tool configuration directory is itself the repository root. These will only become release claims after implementation, review, and the same cross-platform gates used by the current release train.

Try the latest release

Run this from the root of a repository:

npx --yes harness-score

Then look at the first failed checks and ask a practical question: which missing artifact would reduce the most repeated agent mistake in this project?

You can explore the guide, inspect the full changelog, or contribute a detector and reproducible fixture through the GitHub repository.

This article was prepared with AI assistance. Release claims, commands, roadmap language, tags, links, and the current 1.6.4 package metadata were checked against the public repository, documentation, DEV Community, and package registry before publication.

Which part of your AI coding harness is hardest to make visible today: context, feedback, guardrails, or CI?

Validate Card Brands in Node.js with Luhn and credit-card-brand-detector

Fernando Paladini — Sat, 05 Sep 2026 12:36:38 +0000

When a checkout form receives a card number, the first useful question is often not whether the payment will be approved. It is whether the input is structurally plausible and which network rules should be shown to the user.

The open-source credit-card-brand-detector package provides that small client-side or server-side building block. It detects 11 brands, removes spaces and hyphens, and applies a Luhn checksum. It has zero runtime dependencies and exposes CommonJS functions for validation and brand detection.

This tutorial builds a minimal Node.js check, verifies the result with known test numbers, and explains what this kind of validation cannot tell you.

TL;DR

Install version 1.0.1, call validateCreditCard when you need both a boolean result and a brand, and call detectBrand when you only need the network name. The package does not contact a payment processor, authorize a transaction, tokenize data, or prove that a card exists.

Prerequisites

You need:

Node.js 12 or newer. The package declares >=12.0.0 in its metadata.
npm.
A terminal and a small JavaScript file.

The package is released under the MIT license. The examples below target the published npm package version 1.0.1, which is also the version I installed for this walkthrough.

Install the package

Create a directory for the example and install the pinned version:

mkdir card-check-example
cd card-check-example
npm init -y
npm install credit-card-brand-detector@1.0.1

Pinning the version makes the example reproducible. If you use a different version later, check its README and package metadata before copying the behavior into a production application.

Build the smallest useful check

Create check-card.js:

const {
  validateCreditCard,
  detectBrand,
  getBrand,
} = require('credit-card-brand-detector');

const formattedVisa = '4532 0151-1283-0366';
const mastercard = '5555555555554444';

console.log(validateCreditCard(formattedVisa));
console.log(detectBrand(mastercard));
console.log(getBrand(mastercard));

Run it:

node check-card.js

The expected output is:

{ isValid: true, bandeira: 'Visa' }
Mastercard
Mastercard

The Portuguese property name bandeira is part of the package's public return shape. Keep it as-is when consuming the API, or map it to an application-specific name at your boundary.

Understand the two API paths

validateCreditCard(cardNumber) returns an object with isValid and bandeira. It first strips non-digit characters, rejects values shorter than 13 or longer than 19 digits, detects a brand from configured prefixes, and then runs the Luhn calculation.

detectBrand(cardNumber) returns a brand name or null. getBrand is an alias for the same function. This is useful when the UI needs to change an icon or helper message before the complete number is validated.

The implementation checks more specific ranges before broad ones. That matters for Brazilian brands such as Elo, whose configured prefixes can begin with 4, the same first digit used by Visa. A broad prefix check performed first could classify a supported Elo example as Visa.

Add an explicit application boundary

The package accepts a string and normalizes it internally, but your application should decide how to handle empty input, pasted content, and form errors. A small wrapper can keep the package's output separate from UI messages:

const { validateCreditCard } = require('credit-card-brand-detector');

function inspectCardInput(value) {
  if (typeof value !== 'string' || value.trim() === '') {
    return { ok: false, message: 'Enter a card number.' };
  }

  const result = validateCreditCard(value);

  if (!result.bandeira) {
    return { ok: false, message: 'The card network is not recognized.' };
  }

  if (!result.isValid) {
    return { ok: false, message: 'The number failed its checksum.' };
  }

  return { ok: true, brand: result.bandeira };
}

console.log(inspectCardInput('4532015112830366'));

This wrapper deliberately reports a checksum failure as an input problem. It does not imply that a valid checksum means the card can be charged.

Reproduce the verification

The repository README documents these public examples. You can check the package independently with a one-line Node command:

node -e "const p=require('credit-card-brand-detector'); console.log(JSON.stringify({validVisa:p.validateCreditCard('4532015112830366'),mastercard:p.detectBrand('5555555555554444'),formatted:p.validateCreditCard('4532 0151-1283-0366'),unknown:p.detectBrand('1234567890123')}))"

The verified result is:

{"validVisa":{"isValid":true,"bandeira":"Visa"},"mastercard":"Mastercard","formatted":{"isValid":true,"bandeira":"Visa"},"unknown":null}

For an application test suite, add cases for formatting normalization, unknown prefixes, too-short values, each supported network you rely on, and known invalid checksums. Do not use real customer card numbers in tests or fixtures.

Why the check works

Brand detection is prefix matching against the rules in the package source. Luhn validation is a checksum calculation that doubles alternating digits from the right, subtracts nine when a doubled value exceeds nine, and checks whether the total is divisible by ten.

That division of responsibility is useful: prefix rules answer “which configured network might this resemble?” while Luhn answers “does this string satisfy the checksum?” Neither step performs authorization or a network lookup.

Failure modes and security boundaries

There are several important limitations:

A valid Luhn result does not prove that a card is issued, active, funded, or owned by the person entering it.
Prefix tables can become outdated as networks change ranges. Review the package source and release history before relying on a classification for business logic.
The package strips non-digit characters. That is convenient for spaces and hyphens, but it should not replace input limits, rate limiting, or server-side validation.
Never log full card numbers. Avoid putting them in analytics events, exception messages, URLs, screenshots, or support tickets.
Browser-side validation is only a user-experience aid. Payment credentials should be handled through a PCI-compliant payment provider and tokenization flow appropriate to your system.
This package has no payment gateway integration and makes no security guarantee for an application that uses it.

Use test numbers supplied by your payment provider for payment-flow tests. For a real checkout, send payment data only through the provider's documented secure collection mechanism instead of building your own storage path.

FAQ

Does this package charge a card?

No. It only analyzes a string locally.

Does a valid result mean the payment will succeed?

No. Authorization, funds, fraud checks, expiration, and issuer decisions happen elsewhere.

Can I use it with formatted input?

Yes. The implementation removes non-digit characters before checking length, prefixes, and the checksum.

Why is the result property named `bandeira`?

That is the package's documented public API. Map it in your own code if your application uses English field names.

Does it support every card network?

No. The README lists 11 supported brands. Treat null as “not recognized by this rule set,” not as proof that a number is invalid.

Takeaway

credit-card-brand-detector is a focused Node.js utility for early input feedback. Its useful boundary is narrow: normalize a candidate number, identify a configured brand, and run a checksum before the payment workflow begins. Keep that result separate from authorization, and keep payment data out of logs and application storage.

This article was prepared with AI assistance. The commands, package version, API behavior, and example output were checked against the public repository and the installed npm package before publication.

What additional boundary would you test before putting a card-number helper in front of a payment provider?

Keep Rails Design Tokens Reviewable with rails-design-profiles

Fernando Paladini — Fri, 04 Sep 2026 12:37:30 +0000

Design references are useful until they start changing production code by implication.

An AI assistant or a contributor can read a DESIGN.md file and understand a visual direction. That does not mean the application should execute the file, copy an entire stylesheet, or silently adopt a third-party brand. The safer boundary is to review the reference, approve a small set of values, and commit those values as an explicit application contract.

This tutorial shows that workflow with rails-design-profiles, a MIT-licensed Ruby gem for Rails. The stable v0.1.2 release stores profiles in YAML and emits the active profile as --rdp-* CSS custom properties.

TL;DR

Install the gem, run its generator, add a profile to config/design_profiles.yml, and include <%= rails_design_profiles_tags %> in your layout. Rails then emits a small style tag containing only valid token names and safe token values. Your existing CSS decides how to use those variables.

Prerequisites

You need:

Ruby 3.1 or newer.
Rails 7.1 or newer.
A Rails application where you can edit the Gemfile and application layout.
A CSS setup that can consume CSS custom properties.

The gem declares actionview >= 7.1 and railties >= 7.1 as dependencies. Its gemspec identifies the release as version 0.1.2 and the license as MIT.

Install the stable release

Add the gem to your Rails application's Gemfile:

gem "rails-design-profiles", "0.1.2"

Install dependencies and run the generator:

bundle install
bin/rails generate rails_design_profiles:install

The generator creates config/design_profiles.yml and adds this helper to the application layout's <head>:

<%= rails_design_profiles_tags %>

The helper is intentionally small. It reads the active profile, converts accepted tokens into CSS custom properties, and renders one style tag. It does not replace your stylesheet or select a CSS framework.

Define an explicit profile

Open config/design_profiles.yml. The documented shape is a selected profile plus a map of named profiles:

active: editorial
profiles:
  editorial:
    reference: config/design_profiles/references/claude.md
    tokens:
      color-primary: "#c15f3c"
      color-surface: "#f8f6f2"
      color-text: "#24211e"
      font-body: "Newsreader, Georgia, serif"
      space-page: "1.5rem"

The reference field documents where the human-readable context came from. It is metadata for people and tools. The tokens map is the production contract.

Use those variables from the CSS already in your application:

body {
  color: var(--rdp-color-text);
  background: var(--rdp-color-surface);
  font-family: var(--rdp-font-body);
}

.button {
  background: var(--rdp-color-primary);
  padding: var(--rdp-space-page);
}

The gem changes a token name such as color-primary into --rdp-color-primary. The prefix keeps these values easy to locate and reduces accidental collisions with unrelated custom properties.

Import a reference without making it executable

Version 0.1 supports the MIT-licensed VoltAgent/awesome-design-md catalog. List its available references:

bin/rails design:list

Install a reference into your application:

bin/rails design:install[claude]

The task archives the reference at config/design_profiles/references/claude.md and creates an empty claude profile. Read it, discuss which ideas fit your product, and add only the tokens your team approves. Existing references and profiles are not overwritten.

This is an important security and maintenance boundary. The catalog file is content to inspect, not Ruby code to load. The gem downloads it over HTTPS, checks the response status, validates the slug shape, and writes it under the application's configuration directory.

The project also states that it is not affiliated with getdesign.md, VoltAgent, or any referenced brand. Treat an imported reference as an input to review, not as an endorsement or a ready-made theme.

Switch the active profile

After defining another profile, activate it explicitly:

bin/rails design:activate[editorial]

The task updates the active key in config/design_profiles.yml. The new application-wide profile is used on the next response. Because the change is a normal configuration diff, a reviewer can see which values changed before deployment.

Per-session previews and query-string overrides are intentionally outside the first release. If you need a live theme picker, build that as a separate feature with its own authorization and caching design.

Verify the result

There are two useful checks. First, inspect the rendered HTML in a development response. You should find a style tag similar to this:

<style id="rails-design-profiles">:root {--rdp-color-primary: #c15f3c;--rdp-color-surface: #f8f6f2;}</style>

Second, verify that the CSS uses the variables rather than hard-coded replacements. A browser's computed-style panel should show the value flowing from the custom property into the component.

The v0.1.2 test suite covers seven assertions across profile rendering, missing profiles, invalid YAML, reference installation, invalid slugs, activation, and helper output. In a clean checkout, the two Minitest files ran with 7 tests and 9 assertions, with zero failures or errors. The documented gem build also succeeded.

Why this works

The design decision is separation of concerns:

DESIGN.md gives humans and AI tools context about a visual direction.
A reviewed YAML profile records the subset that the product actually accepts.
The helper exposes those values through standard CSS primitives.
Existing components remain responsible for layout, interaction, and accessibility.

That separation makes changes reversible. Removing a token or changing the active profile is a small diff. It also avoids pretending that prose can safely compile an entire interface without review.

Failure modes and limitations

An unknown active profile raises ProfileNotFound. Invalid YAML raises ConfigurationError, as does a missing or malformed profiles mapping. A token is ignored unless its name uses lowercase letters, numbers, and hyphens, and its value matches the gem's conservative character allowlist. This filtering is helpful, but it is not a complete CSS sanitizer or a substitute for reviewing configuration changes.

The active profile is global to the Rails application and evaluated for each response. The first release does not provide user-specific themes, preview sessions, token validation diagnostics, or adapters for arbitrary public catalogs. The README lists those as planned work, so do not present them as current features.

The catalog download is a network dependency. Pin the gem version, review imported files, and commit the archived reference if reproducibility matters. Do not put secrets, user-provided CSS, or untrusted dynamic values into the profile. Keep the helper output under normal Rails content-security-policy and caching review.

FAQ

Does this replace Tailwind or the asset pipeline?

No. The gem emits CSS custom properties that can be consumed by the asset pipeline, Propshaft, Importmap, Tailwind, or custom CSS.

Does importing a reference install its branding?

No. The reference is archived as Markdown and the profile starts empty. Your team chooses the production tokens.

Can I override the profile with a query parameter?

Not in the first release. Profile switching is an explicit application-wide task.

Is the gem a design-system validator?

No. It provides a deliberately small bridge from reviewed configuration to CSS variables. The release roadmap mentions validation and diagnostics as future work.

Takeaway

rails-design-profiles is useful when you want design context to help Rails work without letting reference prose or copied CSS become an invisible production dependency. Keep the reference readable, keep the approved tokens in version control, and let your existing CSS consume the explicit --rdp-* contract.

What review rule would your team require before a design reference is allowed to influence production tokens?

Disclosure: AI assistance was used to organize and edit this tutorial. The project behavior, release metadata, source excerpts, and test results were checked against the public repository and stable v0.1.2 tag.

Plan a Trekking Trip With AI, a Weight Spreadsheet, and the LighterPack SDK

Fernando Paladini — Thu, 03 Sep 2026 13:40:22 +0000

Planning a multi-day trek is a data problem disguised as an adventure. You collect GPX files, weather notes, permit links, and a growing pile of gear receipts. Weight limits show up in airline rules, in your own fitness goals, and in every "do I really need this?" moment at 4,000 meters.

Most hikers end up with the same fragmentation: a spreadsheet here, a LighterPack list there, product links in browser tabs, and half-remembered weights copied from store pages. The list gets stale the moment you buy one more layer or swap a stove.

This tutorial describes a workflow I used while preparing a Salkantay trek repository, generalized so you can adapt it to any hike. The idea is simple:

Use AI to help you plan the trek and normalize messy purchase data.
Store the result in a CSV that acts as the source of truth for weight, price, and status.
Sync that CSV to LighterPack with @paladini/lighterpack, an unofficial TypeScript SDK for LighterPack.

You will not get a magic "upload PDF → perfect pack list" button. You will get a repeatable pipeline you can version in Git, re-run before a trip, and extend with your own rules.

What you are building

Think in three layers:

Layer	Role	Artifact
Planning	Context, route, references	`README.md`, GPX, notes
Inventory	Quantities, weights, prices, purchase status	`gear/items.csv`
Publishing	Shareable pack list with categories and photos	LighterPack list + public link

AI sits on the edges of this system: helping you draft the plan, extracting rows from invoices, and filling gaps when a product page is hard to parse. The CSV stays deterministic. The sync script stays boring. That separation is what makes the workflow trustworthy.

Prerequisites

A LighterPack account (the service is open source and can be self-hosted).
Node.js 20+ for the sync script.
A folder per trek, for example 2026/my-trek/.
An AI assistant (chat or agent) for unstructured inputs: notes, invoices, screenshots.

The SDK is unofficial. It talks to the same web API the LighterPack site uses and authenticates with your normal username and password. Treat those credentials like any other secret.

Step 1 — Let AI help you plan the trek (without owning the truth)

Start with questions AI is good at when you feed it structured context:

Route length, elevation, season, and resupply points.
Group size and shared vs personal gear.
Constraints: vegan food, carry-on-only flights, rental vs owned items.

Ask for a draft checklist by category (shelter, cooking, clothing, safety), not a final weight table. Your job is to reject, merge, and annotate.

A useful prompt pattern:

I am hiking [trail] in [month] with [N] people.
Constraints: [weight limit], [diet], [owned vs to-buy].
Return a table with columns: category, item, model, quantity, notes.
Mark each row as owned, to-buy, or borrow.
Do not invent weights or prices.

Save the narrative plan in README.md and keep evolving it. Do not let the chat transcript become your inventory database. Chats are great for exploration; they are poor as source of truth.

Step 2 — Turn invoices and receipts into spreadsheet rows

This is where AI saves the most tedious work. After you buy gear, you usually have:

PDF or email invoices.
Marketplace order pages (Decathlon, AliExpress, Amazon, and regional stores).
Screenshots with SKU, quantity, and price.

Paste the text (or attach a readable PDF/image) and ask the model to emit CSV-shaped rows aligned with your schema.

Recommended columns:

category,item,model,quantity,unit_price,total_price,unit_weight_kg,total_weight_kg,baggage,status,notes,url

Example prompt:

Extract gear purchases from this invoice into CSV rows.
Schema: category,item,model,quantity,unit_price,total_price,unit_weight_kg,total_weight_kg,baggage,status,notes,url
Rules:
- baggage is "carry-on" or "checked" when known, else empty.
- status is "owned", "to-buy", or "rent".
- unit_weight_kg only if explicitly stated; otherwise leave blank.
- url: product page if visible, else empty.
- One row per line item; quote fields that contain commas.
Output only CSV, no commentary.

Review every row. AI will misread bundles ("2 pairs of socks" vs quantity 2), confuse shipping with product weight, and hallucinate URLs. Weights from manufacturer pages are often missing on invoices — look them up once, then store them in the CSV.

For a two-person trip, decide early whether quantities are per person or shared and document that in notes. LighterPack supports quantity per line item; your spreadsheet should match how you think about the pack.

Step 3 — Treat the CSV as the contract

Once reviewed, commit gear/items.csv to Git (or keep it locally if you prefer). This file is the contract between:

your planning spreadsheet,
your automation script,
and the published LighterPack list.

Conventions that paid off in practice:

Categories map directly to LighterPack categories (Camping, Clothing, Hydration, etc.).
Weights in kilograms in the CSV; convert to grams in code (Math.round(kg * 1000)).
Worn and consumable flags are derived with small keyword lists (boots, poles, freeze-dried meals) instead of extra columns.
Product URLs enable image resolution later; empty URLs are fine for generic items.

A minimal row might look like:

Clothing,Trekking boots,Hoka Speedgoat 6,2,1000.0,2000,0.267,0.534,carry-on,owned,,

Step 4 — Sync to LighterPack with TypeScript

Install the SDK:

npm install @paladini/lighterpack

Create scripts/lighterpack/.env (never commit it):

LIGHTERPACK_USERNAME=your_username
LIGHTERPACK_PASSWORD=your_password

The sync script reads the CSV, groups items by category, resolves images, and creates the list in one batch call. The core pattern:

import { LighterPackClient } from '@paladini/lighterpack';

const lp = new LighterPackClient({
  username: process.env.LIGHTERPACK_USERNAME!,
  password: process.env.LIGHTERPACK_PASSWORD!,
});

await lp.account.setCurrencySymbol('$'); // or €, £, etc.

const detail = await lp.batch.createListWithItems({
  name: 'My Trek 2026 (2 people)',
  description: 'Generated from gear/items.csv',
  categories: [
    {
      name: 'Shelter',
      items: [
        {
          name: '2-person tent',
          description: 'Naturehike Star River 2 · Checked bag',
          qty: 1,
          weight: 1950, // grams
          weightUnit: 'g',
          price: 900,
          url: 'https://example.com/tent',
          worn: false,
          consumable: false,
        },
      ],
    },
  ],
});

await lp.lists.setOptionalFields(detail.listId, {
  images: true,
  price: true,
  worn: true,
  consumable: true,
  packWeight: true,
});

const shareUrl = await lp.lists.generateShareLink(detail.listId);
console.log(shareUrl);

createListWithItems is the workhorse: one round trip to scaffold categories and items. For large lists (50+ lines), this is far less fragile than clicking through the UI.

Map CSV columns to SDK fields explicitly:

name ← item
description ← model, notes, baggage, status (joined as readable text)
qty ← quantity
weight ← unit_weight_kg converted to grams
price ← unit_price
url ← url

Step 5 — Product images (expect breakage)

LighterPack can display item photos from external URLs, but retailer CDNs often block hotlinking or return generic Open Graph images. In a real sync of ~50 items, a majority of naive og:image URLs failed.

A more reliable approach:

Resolve image URLs per product (Decathlon VTEX packshots, AliExpress media CDN, manufacturer sites).
Download images locally with a small Python script.
Upload with lp.items.uploadImage(itemId, { buffer, filename, mimeType }).

Local upload beat setImageUrl for visibility on the share page. Keep downloaded binaries out of Git; store only the resolver map and scripts.

Verification

After npm run sync:trek (or your own script name), check:

Totals — LighterPack pack weight and price should match your spreadsheet sums within rounding.
Categories — item counts per category match CSV grouping.
Flags — boots and poles marked worn; meals marked consumable.
Share link — open the generated URL in a private window.

Example output from a successful run:

{
  "listId": 17,
  "name": "Salkantay 2026 (2 people)",
  "weightGrams": 25100,
  "price": 14489.78,
  "shareUrl": "https://lighterpack.com/r/example"
}

Re-run the sync after CSV edits. Idempotency strategy: find an existing list by name, delete it, recreate. Crude but clear for personal repos.

Security and boundaries

Never commit .env, passwords, or invoice PDFs with personal data.
Rotate your LighterPack password if it was ever pasted into a chat or log.
The SDK session is in-memory; changing your account password revokes access.
AI-generated weights and prices are suggestions until you verify them against specs or a scale.

Tradeoffs and limits

Choice	Benefit	Cost
CSV as source of truth	Git-diffable, scriptable	Manual review after AI extraction
Batch SDK create	Fast, repeatable	Deletes/recreates list on full sync
AI invoice parsing	Less typing	Requires validation; not fully autonomous
Local image upload	Reliable thumbnails	Extra download/upload step

This workflow is optimized for multi-day treks where gear lists are large and shared. For a day hike, a single LighterPack list edited by hand is probably enough.

What I would do next

Add a make check that validates CSV totals and required fields before sync.
Store trek metadata (dates, group size) beside the CSV for richer list descriptions.
Wire the MCP server from the same SDK family if you want an agent to query the list without running scripts.

If you try this pipeline, start with ten items end to end before importing a full expedition list. Fix the schema once, then scale.

Question for readers: Where do you draw the line between "AI drafts the row" and "I require a photo of the scale / spec sheet before it enters the CSV"? I still hand-verify every weight that affects carry-on compliance.

Primary sources

LighterPack — pack list service.
LighterPack (open source) — self-hosting option.
@paladini/lighterpack on npm — TypeScript SDK used in this workflow.
lighterpack-sdk on GitHub — SDK source and API reference.

Restore Sanitized MCP Configurations Without Committing Secrets

Fernando Paladini — Thu, 03 Sep 2026 12:35:25 +0000

AI assistants are useful only when their tools are configured consistently. That consistency becomes risky when a client configuration contains an API key, a browser profile, cookies, or a copied storage state file.

The practical problem is not just "where do I put the MCP server?" It is how to share a reproducible setup without turning a public repository into a credential container.

This tutorial uses paladini/agent-skills to restore sanitized MCP client examples. You will clone the repository, inspect its placeholders, copy one configuration locally, and run the repository's deterministic checks. The same workflow applies to other public configuration examples.

What the repository provides

The repository collects reusable Agent Skills and sanitized configurations for DEV.to, Medium, and LinkedIn workflows. Its README says the configuration examples contain placeholders rather than real credentials, and its publishing guardrails keep the final public action supervised.

The useful design decision is the separation between a shareable shape and a local secret. A repository can document the command, arguments, environment-variable name, and publication boundary. It should not contain the value of DEV_TO_API_KEY, a password, a cookie, an MFA code, or a browser storage state.

This is also consistent with how MCP stdio transport works: the client launches the server as a subprocess and communicates over standard input and output. The client therefore needs a local command and local environment, but those values do not need to be committed to Git. See the MCP transport specification for the transport behavior.

Prerequisites

You need:

Git;
Python 3.11 or newer for the bundled validation scripts;
an MCP-compatible client if you want to connect a server after validation;
a local directory outside the repository for real secrets and persistent browser profiles.

The checkout used for this tutorial was the repository's main branch at commit f54fb0256aaf0d527f52d140a1c9996ea6925d26, dated 2026-07-21. The repository declares the MIT license in LICENSE. There is no package installation step for the configuration collection itself.

Clone and inspect before copying

Start with a disposable checkout:

git clone https://github.com/paladini/agent-skills.git
Set-Location agent-skills
git log -1 --format="%H %cs"
Get-ChildItem -Recurse mcp-configs

The important files for a DEV.to setup are:

mcp-configs/
  devto/
    .env.example
    client.json.example
    codex.toml.example
  publishing-guardrails.md

Read the example before replacing anything. The current TOML example contains a deliberately invalid executable path and a placeholder secret:

[mcp_servers.devto]
command = "C:\\PATH\\TO\\uv.exe"
args = ["--directory", "C:\\PATH\\TO\\devto-mcp", "run", "server.py"]

[mcp_servers.devto.env]
DEV_TO_API_KEY = "<local>"

This is a template, not a configuration you can run unchanged. Replace the paths in your local client configuration only. Keep the committed example unchanged so another person can understand which values are required.

Restore a local configuration safely

On Windows, copy the example to the local Codex configuration file, then edit the local copy. The repository's README recommends merging the table into %USERPROFILE%\.codex\config.toml.

$repo = (Resolve-Path .).Path
$config = Join-Path $env:USERPROFILE ".codex\config.toml"
Copy-Item "$repo\mcp-configs\devto\codex.toml.example" "$config.devto-example"
notepad "$config.devto-example"

Use an absolute path to the MCP server checkout and the uv.exe executable on your own machine. Put the real key in the client-managed environment or secret store. Do not paste it into the repository file, the example file, a shell history entry, or a tutorial.

If your client accepts JSON instead of TOML, the repository also provides client.json.example with the same structure. The two formats are alternatives. Do not register both unless you intentionally want two server entries.

After editing the real local configuration, verify that the file is outside the Git repository and that the placeholder is not being used accidentally:

$config = Join-Path $env:USERPROFILE ".codex\config.toml"
Resolve-Path $config
Select-String -Path $config -Pattern "mcp_servers|DEV_TO_API_KEY|REPLACE_WITH_LOCAL_SECRET"
git -C $repo status --short

The last command should show no change caused by the local secret configuration. The Resolve-Path result should point to your user configuration directory, not the cloned repository.

Validate the public examples

The repository includes a validator for the committed MCP examples. It checks that the expected JSON and TOML examples exist, parses them, checks the mcpServers and mcp_servers structures, and scans for likely credentials.

python scripts\validate_mcp_configs.py

Expected result:

OK: sanitized MCP configurations are valid

The repository also includes three unit tests for the DEV.to article validator. Run them from the checkout:

python -m unittest discover -s skills\devto-publish-expert\scripts -p "test_*.py"

The observed result for the current checkout was three passing tests. These checks do not prove that an external MCP server is reachable, that an account is authenticated, or that a platform's UI will remain unchanged. They prove a narrower and useful property: the examples are structurally valid and do not contain values matching the repository's credential patterns.

Browser profiles need a different boundary

The Medium and LinkedIn examples use Playwright MCP rather than an API key in the repository. Their local configuration points to a persistent browser profile outside the Git checkout. That profile can contain cookies and authenticated sessions, so it must be treated as private data.

The official Playwright MCP documentation describes persistent, isolated, and extension-based browser modes. It also warns that Playwright MCP is not itself a security boundary. The repository therefore recommends one profile per platform, manual login and MFA, headed browser sessions for publishing workflows, and no committed cookies or storage state.

If you connect to an existing browser, pay special attention to scope. The official Playwright browser connection guide explains that extension mode can reuse logged-in sessions, cookies, and installed extensions. That convenience is exactly why the profile and connection should remain local and supervised.

Failure modes to expect

The client cannot start the server

Check the executable and server directory in the local configuration. A placeholder path from the public example is expected to fail. Also check that the server writes protocol messages to stdout and diagnostics to stderr, as the repository README requires for the DEV.to server.

The server starts but authentication fails

Confirm the environment variable name and the local secret source. Do not solve this by adding the key to codex.toml, client.json, .env.example, or a Git-tracked file. Rotate a key if it was ever committed or pasted into a shared log.

A browser session opens the wrong account

Stop the workflow and inspect the local profile choice. Do not export cookies or storage state to debug it. Use a separate profile per platform and log in manually. A fresh isolated session is safer for testing, but it will not retain the existing login.

The validation script reports a possible credential

Treat the warning as a real review item. Inspect the matching file, remove the value from Git history if necessary, rotate the exposed credential, and rerun the validator. A green result is not a substitute for reviewing the diff.

Security boundaries

Sanitized examples reduce accidental disclosure; they do not make every MCP server safe. An MCP server may be able to read files, call network services, control a browser, or publish externally. Review the server source, pin versions deliberately, use least-privilege credentials, and test read-only operations before write operations.

For publishing workflows, the repository's guardrails say to research and validate first, save a draft when possible, show the final destination and content, and stop before the final public action. Approval to open an editor or save a draft is not the same as approval to publish.

FAQ

Can I commit a real path?

Prefer a placeholder path in a public example. Absolute paths can disclose usernames, private directory layouts, or mounted volumes. Keep machine-specific paths in the local client configuration.

Can I use `.env.example` for the real key?

No. It is a variable-name reference. Put the actual value in a local secret manager or client environment that is excluded from Git.

Does the validator test the remote platform?

No. It validates the repository's local JSON, TOML, and credential patterns. Account access and platform behavior require a separate, supervised smoke test.

Why keep both JSON and TOML examples?

Different MCP clients accept different configuration formats. Keeping equivalent examples makes the transport shape portable while leaving paths and secrets local.

Takeaway

A reusable MCP setup should share intent and structure, not authentication state. Clone the public Agent Skills repository, inspect its placeholders, copy an example into a user-level configuration, keep profiles and keys outside Git, and run the deterministic validators before connecting a client.

What is the smallest read-only smoke test you require before allowing an MCP server to perform a write or publish action?

AI assistance disclosure: This tutorial was researched and drafted with AI assistance. Repository contents, the current example configuration, validation scripts, and cited primary documentation were checked before publication.

Turn Moodle Pages into NotebookLM Markdown with a Local Chrome Extension

Fernando Paladini — Wed, 02 Sep 2026 12:37:26 +0000

Moodle content is rarely in one convenient document. A course can spread its material across lessons, pages, files, and embedded videos. Copying each page into a notebook by hand is slow, and a generic scraper can lose the course and module boundaries that make the material useful later.

This tutorial shows a local workflow using Moodle Content Extractor for NotebookLM. You will load the open-source Manifest V3 extension, enable capture for a Moodle site, browse the pages you want, and export one Markdown file with course and module structure preserved.

The project is a browser extension, not a hosted crawler. It processes captured content in the browser and creates files only when you request an export. That boundary matters when course pages contain private or copyrighted material.

What you will build

The workflow looks like this:

Install the extension from the Chrome Web Store, or load the source as an unpacked extension.
Configure the base URL of your Moodle installation.
Start capture through the extension popup.
Browse the lesson and activity pages you want to study.
Stop capture and export the course as Markdown.
Upload that Markdown file to NotebookLM yourself if you want a source-grounded study notebook.

The repository's current stable release is v1.4.0. The release notes describe a fix for same-tab Moodle navigation, protection for corrupt or empty module records, and URL normalization for lesson modules.

Prerequisites

You need:

Chrome, Edge, or another Chromium-based browser that supports Manifest V3 extensions.
Access to a Moodle site that you are allowed to read and export.
A local copy of the extension only if you choose the unpacked installation.
NotebookLM as an optional destination. The extension does not call NotebookLM or require a NotebookLM account.

The release package has no dependency installation step and no build step. If you load from source, use the v1.4.0 tag so the files you test match the stable release.

Install from source

The Web Store is the shortest path. For a source-based installation, clone the stable tag:

git clone --branch v1.4.0 --depth 1 https://github.com/paladini/extract-moodle-content-to-notebook-lm-extension.git
cd extract-moodle-content-to-notebook-lm-extension

Open chrome://extensions in Chromium. Turn on Developer mode, choose Load unpacked, and select the cloned directory. The project is a zero-dependency extension, so there is no npm install or build command to run.

The manifest declares Manifest V3, a background service worker, a popup, and permissions for activeTab, scripting, storage, and downloads. It also declares *://*/* host access so capture can continue across page navigations after you enable it.

Capture a Moodle course

Click the extension icon and save your Moodle base URL. A value such as https://moodle.example.edu is a placeholder. Use the origin and path that actually identify your installation, without inventing a URL for a site you do not control.

Click Start Capture, then browse the Moodle lesson or activity pages you want to include. The extension groups pages using Moodle breadcrumbs and page context. When you are finished, click Stop Capture. You can then export one course or export all captured courses.

The important operational detail is explicit capture mode. The extension does not treat every page you visit as course content. Its content script checks the configured Moodle base URL and exits on pages that do not match it. This is documented in the project's permission justification.

An export is structured Markdown rather than a flat text dump. A simplified example looks like this:

# Course Name

## Module: 1.1 Introduction to Databases
Type: lesson
Captured at: 2026-03-11T02:30:00.000Z

[extracted content]

### Videos
- https://youtube.com/example

### Resources
- https://moodle.example.edu/pluginfile.php/example.pdf

The timestamp and URLs are useful for checking where a passage came from and for keeping exports and backups consistent. The actual export includes the captured page content and any detected video or attachment links that the extractor supports.

Why the local design is useful

The extension stores course data in Chrome extension storage. The background service worker handles persistence, while the content script extracts content from a matching Moodle page. The popup provides capture controls, course management, export actions, and backup or restore actions.

This division keeps the workflow understandable:

content.js reads the page and extracts course material.
background.js groups and stores records in chrome.storage.local.
popup.js starts and stops capture and turns stored records into downloads.

Chrome's Storage API documentation describes storage.local as extension-local storage. Chrome documents a default local-storage limit of 10 MB, so a very large course export may need to be split or managed carefully. The extension's local backup and recovery features reduce the chance that a failed write silently destroys the only copy in the browser, but they do not replace an external backup of exported files.

The downloads permission is used for explicit Markdown and JSON export actions. Chrome's downloads API reference confirms that this permission is required to initiate downloads. The extension does not need a remote server for normal use, and its privacy policy says data leaves the browser when you explicitly export, import a backup, or upload an exported file to another product.

Verify the installation before capturing real content

You can perform a low-risk source check before granting access to a Moodle site. Confirm that the manifest reports version 1.4.0, that the background service worker is background.js, and that the referenced popup and icon files exist in the directory.

On a machine with Node.js, the JavaScript files can also be parsed without executing them:

node --check background.js
node --check content.js
node --check popup.js

The commands check syntax only. They do not prove that a particular Moodle theme, login flow, embedded video, or attachment format will extract correctly. For a functional check, use a course page you are permitted to process, capture one lesson, export it, and inspect the resulting Markdown before uploading it anywhere.

Your verification checklist should be concrete:

The course name and module headings are present.
The captured text matches the page you selected.
Video and resource links point to the expected locations.
A page outside the configured Moodle base URL was not added as course content.
The exported file opens as ordinary Markdown and does not contain unexpected credentials or private browser data.

Failure modes and limits

If a newly visited lesson is missing, confirm that capture mode is still enabled and that the page matches the configured base URL. Same-tab navigation was specifically addressed in the v1.4.0 release, but a Moodle installation can still use custom page structures that the extractor does not recognize.

If an export is incomplete, inspect the source page and the extension's supported extraction behavior. Embedded content can require its own permissions or may not expose readable text in the page DOM. A linked PDF or presentation is represented as a resource link; the extension does not claim to convert every attachment into Markdown.

If storage writes fail, reduce the amount captured in one browser storage set and export more frequently. Chrome's storage quota is a real limit, not a promise that an arbitrarily large course can stay in one local record.

Most importantly, local processing is not the same as unrestricted use. Moodle content may contain student information, licensed textbooks, assessments, or internal course material. Capture only what you are authorized to access, keep exported files private, and review the destination's data-handling terms before uploading them. The extension's privacy policy documents its intended local-first behavior, but it cannot control what happens after you export a file.

FAQ

Does this require an API key?

No. The documented workflow uses the browser extension and local browser storage. NotebookLM is an optional destination, not an API dependency.

Does it crawl Moodle in the background?

No. You enable capture through the popup and browse the pages yourself. The extension injects its capture logic for matching pages while capture mode is active.

Can it export every file attached to a course?

It extracts links to supported resources such as PDF, DOCX, and PPTX. Those links are included in the Markdown; the project does not claim to transform every attachment into text.

Is the current branch identical to the release?

Not necessarily. This tutorial targets the stable v1.4.0 tag. If you use the default branch, inspect its manifest and documentation again because unreleased changes can alter behavior.

Takeaway

A useful NotebookLM source starts before the AI notebook: it starts with a clean, traceable input. This extension turns a user-selected Moodle browsing session into course and module-aware Markdown while keeping capture and export actions visible.

The practical next step is to test one permitted lesson, inspect the Markdown, and only then decide whether the local export is complete enough for your study workflow.

What Moodle structure causes the most trouble in your own courses: breadcrumb grouping, embedded media, or attached documents?

AI assistance disclosure

AI assistance was used to help organize and edit this tutorial. The repository documentation, stable release metadata, Chrome API documentation, source checkout, and syntax checks were reviewed before publication. Claims about the project are limited to those sources and the documented workflow.

DEV Community: Fernando Paladini

Build a Draft-First Medium Publishing Agent with MCP

TL;DR

What you will build

Prerequisites

Install the stable package

Create the local browser session

Register the MCP server

Import a DEV.to article as a draft

Review the actual editor

Apply a targeted correction

Verify success before publishing

Why this design works

Failure modes and security boundaries

The session is missing or expired

The import does not complete

Medium selectors stop matching

Sensitive data appears in the draft

FAQ

Does MCP publish automatically?

Do I need a Medium API key?

Can I use a personal blog instead of DEV.to?

Is the workflow production-proof?

AI assistance disclosure

Takeaway

Sync AI Guidance Across Repositories with a Reviewable GitHub Action

TL;DR

Prerequisites

1. Create the shared files

2. Add sync-config.json

3. Add the GitHub workflow

4. Verify the dry run

Expected result

Why this works better than manual copying

Failure modes and limitations

The token can reach too much

deleteOrphans can remove synced files

Shared guidance is not automatically correct

It does not merge the result

FAQ

Can I sync directories such as .cursor/rules?

Can I preview changes without creating a pull request?

Does it support files outside GitHub?

Where should secrets go?

AI assistance disclosure

Takeaway

Add 36 Local Developer Utilities to Cursor with an MCP Plugin

TL;DR

Prerequisites

Install the plugin in Cursor

Understand the one-file configuration

Try the minimal workflow

Verify the process without Cursor

Why this setup works

Failure modes and boundaries

FAQ

Does it need an API key?

Does it work outside Cursor?

Does local mean no network activity?

Can it verify a JWT signature?

Takeaway

Download Authorized Circle Course Videos with Python and Playwright

TL;DR

Prerequisites

Start with a dry run

Download after checking the plan

Understand the local files

Useful options

Verify the installation locally

Failure modes and limits

FAQ

Does this upload my course to an API?

Can I reuse my normal Chrome profile?

Can I use it for any video URL?

Why run --dry-run first?

Takeaway

AI assistance disclosure

Govern AI-Assisted Specs in Git with SpecGov

TL;DR

Prerequisites

2. Add `sync-config.json`

`deleteOrphans` can remove synced files

Can I sync directories such as `.cursor/rules`?

Why run `--dry-run` first?

The documented `npx` command cannot resolve

Why is the result property named `bandeira`?