DEV Community: Fernando Paladini

Build a Multilingual React Reflection Portal with GitHub Pages

Fernando Paladini — Mon, 09 Nov 2026 14:35:08 +0000

If a daily-content project starts as a folder of JSON files, the first useful web interface does not need a database server. It needs a predictable data shape, a small client-side state model, and a deployment target that can serve static files.

This tutorial builds that path with AA Daily Reflections Database, an open-source React portal that publishes English, Spanish, French, and Brazilian Portuguese data as JSON, CSV, and SQLite. The goal is not to reproduce its reflection text here. The goal is to understand the reusable engineering pattern: select a language, select a date, load one static data file, and deploy the result as a static site.

TL;DR

Clone the repository, install its Node.js dependencies, run the data-copy step, and build the React app. The portal keeps the selected language and date in localStorage, fetches the matching language JSON from public/data, and uses PUBLIC_URL so the same build can work locally or beneath a GitHub Pages project path.

The repository currently targets React 18.2.0 and react-scripts 5.0.1 in package.json. The live site is available on GitHub Pages.

Prerequisites

You need:

Node.js and npm
Git
A browser
A GitHub repository if you plan to publish your own fork

The project also includes Python, PHP, Go, and JavaScript examples for reading the SQLite database. This walkthrough focuses on the React portal and its static JSON boundary. See the repository's examples guide for the other language-specific paths.

1. Get the project and inspect the data boundary

Clone the repository and enter it:

git clone https://github.com/paladini/aa-daily-reflections-database.git
cd aa-daily-reflections-database

The repository stores the browser-facing files in public/data. Each JSON record has a date, language, title, quote, reflection text, and source reference. The data README documents the same fields and also shows the SQLite schema.

That separation matters. The React app does not need a server endpoint for every date. It can fetch one language file, keep it in memory, and find the requested date locally. Static hosting is enough for this read-only workflow.

2. Install dependencies and build the portal

Install from the lockfile, then run the production build:

npm ci
npm run build

The prebuild script runs npm run copy-data first. That script copies the four language files into public/data, which is the location the browser service reads at runtime. The build then emits a static build directory.

If you want to inspect the development version before building, run:

npm start

Open the local address shown by Create React App. The application uses the current date as its initial selection and starts in Brazilian Portuguese. You can change both values from the interface.

3. See how language selection becomes a file request

The central mapping lives in src/context/AppContext.js. It maps an application language key to a concrete public filename:

export const LANGUAGES = {
  'pt-br': {
    code: 'pt-br',
    name: 'Portuguese (Brazil)',
    file: 'daily_reflections_brazilian-portuguese.json',
  },
  en: {
    code: 'en',
    name: 'English',
    file: 'daily_reflections_english.json',
  },
};

The current source contains all four languages. The important design choice is that the UI does not construct arbitrary paths from user input. It selects a file from a fixed allowlist. That keeps the fetch boundary easy to audit.

The same context stores language and selectedDate, then persists them under two local-storage keys. A visitor can return later and keep the last selected language and date on that browser. This is convenience state, not account data, and it never needs a server session.

4. Load one language file and find one date

The data service in src/services/reflectionService.js caches each loaded language file. Its core path is equivalent to this:

const dataCache = {};

const loadLanguageData = async (lang) => {
  if (dataCache[lang]) return dataCache[lang];

  const languageInfo = LANGUAGES[lang];
  const baseUrl = process.env.PUBLIC_URL || '';
  const response = await fetch(
    `${baseUrl}/data/${languageInfo.file}`,
  );

  if (!response.ok) {
    throw new Error(`Could not load data: ${response.status}`);
  }

  const data = await response.json();
  dataCache[lang] = data;
  return data;
};

export const getReflection = async (lang, date) => {
  const data = await loadLanguageData(lang);
  return data.find((item) => item.date === date) || null;
};

The PUBLIC_URL prefix is important on GitHub Pages. A project site is served below a path such as /aa-daily-reflections-database, not necessarily from /. The prefix lets Create React App provide the correct base path during the build while keeping local development simple.

5. Verify the result without trusting the screen alone

Use the build output and the browser network panel as two separate checks.

First, confirm that the build created the copied files:

test -f build/data/daily_reflections_english.json
test -f build/data/daily_reflections_brazilian-portuguese.json

On PowerShell, use:

Test-Path build/data/daily_reflections_english.json
Test-Path build/data/daily_reflections_brazilian-portuguese.json

Then open the app and change the language. In the browser's Network panel, verify that the request changes to the corresponding file under data/. Change the date and confirm that the displayed record changes without a server-side API request.

Finally, refresh the page. The selected language and date should be restored because the context writes them to localStorage. If a JSON request returns 404, inspect the base path first. A missing PUBLIC_URL is a common static-hosting failure mode.

6. Publish the static build

The repository already includes a deploy script using the gh-pages package:

npm run deploy

Before using it, review the generated build directory and confirm that the repository's Pages configuration matches the branch and path you intend to publish. GitHub Pages is a static host here. It does not execute the React code on the server and it cannot provide private storage for reflection data or user preferences.

The project also generates a sitemap as part of its deployment-oriented script. Read scripts/generate-sitemap.js before adapting the domain or path for a fork. SEO metadata is only useful when its canonical URLs match the site that is actually being served.

Why this pattern works

This architecture matches the problem's access pattern:

The data is read-heavy and changes infrequently.
Each language can be downloaded independently.
Date selection is a local lookup over an already loaded array.
The UI needs no authentication or mutation endpoint.
The deployment artifact is ordinary HTML, JavaScript, CSS, and JSON.

The tradeoff is equally clear. Every browser that uses a language downloads that language's JSON file, and searching the full collection happens in the browser. If the corpus grows substantially, replace the array lookup with a generated index or a query service. Do not add a database server merely because the source data is also available as SQLite.

Limitations and security boundaries

The repository's MIT license covers the software compilation and examples, but its legal notice separately says that the original Alcoholics Anonymous materials remain copyrighted and that the compilation is unofficial. Do not treat the MIT notice as permission to republish the underlying literature without checking the rights for your use case. The project links to aa.org for official resources.

The portal also is not a medical service, a replacement for a recovery group, or a guarantee that a translation is official. Keep those boundaries visible if you fork it. Do not put private user notes into this static dataset: GitHub Pages publishes the generated files publicly.

FAQ

Do I need a backend?

Not for the included read-only portal. The browser fetches static JSON and performs the date lookup locally.

Why keep JSON, CSV, and SQLite?

They serve different consumers. JSON is convenient for browser and small scripts, CSV is useful for analysis, and SQLite is useful when a client needs indexed queries or joins.

Can I add another language?

Add a validated data file, register it in the language allowlist, copy it into public/data, and update the UI labels and documentation. Verify dates, encoding, attribution, and rights before publishing.

Takeaway

A multilingual daily-content portal can remain simple when the data contract is explicit. Start with a fixed language allowlist, cache one static file per language, persist only non-sensitive preferences, and make the deployment path part of the verification checklist.

What would you add first to this pattern: a generated search index, an accessibility test suite, or a small API for clients that cannot download the full language file?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. The repository links, commands, architecture notes, limitations, and security boundaries were checked against the current public repository and live site before publication.

Choose an ActiveAdmin Theme with a Reviewable Rails Checklist

Fernando Paladini — Wed, 04 Nov 2026 12:40:47 +0000

ActiveAdmin makes it quick to build an administrative interface in Rails, but the default interface is not always the right fit for a team. The harder part is often not writing CSS. It is choosing a theme without losing track of its source, compatibility, maintenance status, or the small Rails overrides that change behavior.

This tutorial shows a reviewable way to use activeadmin-themes: treat the repository as a curated starting point, inspect the linked theme source before installing anything, and keep any local Rails override explicit. The repository is a catalog, not a theme gem or a full Rails application.

TL;DR

Clone the catalog, choose a theme whose upstream repository you can inspect, record the exact dependency and asset instructions from that upstream project, and keep custom behavior in your Rails application. If you want to suppress ActiveAdmin's default CRUD flash messages, the catalog documents a small initializer patch. Verify that patch in your own test environment because the catalog does not test every ActiveAdmin and Rails combination.

Prerequisites

You need:

A Rails application that already uses ActiveAdmin.
Ruby and Bundler working for that application.
Git, so you can inspect the catalog and the upstream theme repositories.
A test or staging environment where you can exercise an ActiveAdmin create, update, and destroy action.

The catalog itself is a public MIT-licensed repository owned by Fernando Paladini. Its README is a Markdown list of themes and links. It does not install a theme, select one automatically, or guarantee that a linked project still supports your versions.

1. Inspect the catalog as evidence

Start by cloning the exact repository you are reviewing:

git clone https://github.com/paladini/activeadmin-themes.git
cd activeadmin-themes
git log -1 --format='%H %cI %s'

The README currently lists projects such as Active Admin Flat Skin, Active Admin Theme, Active Bootstrap Skin, ActiveMaterial, Arctic Admin, and Fuji Admin. Each entry links to an upstream repository or RubyGems package. That distinction matters: activeadmin-themes is a directory, so the linked project is the source of truth for installation commands and version support.

Before choosing a theme, open its upstream repository and check at least these items:

The installation instructions and dependency names.
The supported ActiveAdmin, Rails, Ruby, and asset pipeline versions.
The license and the latest meaningful activity.
Whether the project expects Sass, Tailwind, importmaps, Webpacker, or another asset path.
Whether the screenshots match the current code, rather than only an old release.

Do not copy a Gemfile line from the catalog because the catalog does not provide one. Copy it only from the upstream project's current documentation or release instructions, then pin and review it like any other dependency.

2. Keep the application change small

A theme should change the presentation layer. Application-specific behavior should stay in your application. For example, the catalog includes a documented initializer that suppresses ActiveAdmin's default CRUD flash messages:

# config/initializers/active_admin_disable_default_flash_messages.rb
Rails.application.config.to_prepare do
  ActiveAdmin::ResourceController.class_eval do
    private

    def set_flash_message(*)
      # Keep ActiveAdmin from overriding the flash hash.
    end
  end
end

This is a Ruby monkey patch. It is not a general security control, and it does not remove every notification your application might create. It changes a private controller method so it can become sensitive to ActiveAdmin upgrades. Keep the file small, add a comment explaining why it exists, and review it whenever ActiveAdmin changes.

If your application needs flash messages for accessibility or workflow feedback, do not apply this patch blindly. A better choice may be to replace the default message with an application-specific message, or to style the existing message through the chosen theme.

3. Verify the behavior in Rails

Restart the Rails server after adding an initializer. Then exercise one representative resource in a test or staging environment:

bin/rails db:prepare
bin/rails server

Open ActiveAdmin in a browser and test these paths:

Create a record and confirm the result is understandable without relying on the default CRUD flash.
Update a record and confirm validation errors remain visible.
Destroy a record and confirm the redirect and authorization behavior are unchanged.
Check a narrow viewport and keyboard navigation after the theme assets load.

The expected result is not simply “the page looks different.” You want a documented theme choice, a reproducible dependency change, and application behavior that remains understandable after the visual change. If you cannot explain where an asset came from or which version supports your ActiveAdmin setup, the review is incomplete.

For a quick repository-level check, search the catalog for the documented override and inspect the Markdown around it:

rg -n -C 8 "set_flash_message|ActiveAdmin::ResourceController" README.md

That command verifies the current catalog contains the example. It does not prove that your Rails application loads the initializer correctly. Only your application's test or staging run can do that.

Why this workflow works

The catalog separates discovery from adoption. Discovery is cheap: you can compare several themes in one place. Adoption is deliberately slower: the upstream project must provide the dependency contract, asset instructions, and compatibility evidence.

That separation also makes reviews easier. A pull request can show the selected upstream URL, the dependency diff, the asset configuration, and the screenshots or browser checks that justify the choice. Future maintainers do not have to guess whether a line came from the catalog, the theme author, or a local workaround.

The same principle applies to the flash-message patch. It is useful because it is small and visible, but it is risky because it reaches into a controller implementation detail. Keeping it as a named initializer makes that risk searchable.

Failure modes and honest limits

The theme is listed but no longer works

The catalog is not a compatibility matrix. A linked repository can be archived, renamed, or designed for an older ActiveAdmin release. Treat every entry as a lead and re-check the upstream source before adding a dependency.

The asset pipeline is different

A theme built for Sass is not automatically compatible with a Tailwind-based ActiveAdmin application, and a theme's screenshots do not tell you how it is loaded. Follow the upstream instructions for your asset system and verify the compiled output in a real environment.

The patch hides useful feedback

Suppressing default CRUD messages can make an admin workflow harder to understand. Preserve validation errors, authorization failures, and any feedback your operators need. Prefer a replacement message when the workflow requires confirmation.

A private API changes

ActiveAdmin::ResourceController and set_flash_message are implementation details for this purpose. A future ActiveAdmin release can change them. Pin versions according to your application's policy, run the relevant tests, and remove the patch if the upstream behavior changes.

The repository contains old examples

The catalog is a curated list, not a release artifact. Its README can remain useful while some linked projects age. Record the date and commit you reviewed in your project decision log.

FAQ

Does activeadmin-themes install a theme?

No. It catalogs themes and links to their upstream projects. Installation belongs to the selected project's documentation.

Is the flash-message initializer required?

No. It is an optional documented example. Use it only when your application has a clear reason to change the default behavior.

Can I use a listed theme in production?

The catalog does not make that decision for you. Check the upstream license, maintenance, compatibility, security posture, and your own regression checks.

What should I contribute back?

The README asks maintainers to submit a pull request or open an issue when they find a new ActiveAdmin theme. Include the theme's canonical upstream link and enough evidence for another maintainer to review it.

Takeaway

Use activeadmin-themes as a reviewable index, not as a dependency. Choose an upstream project, verify its contract, keep local Rails overrides explicit, and test the admin workflows that your operators actually use.

Have you found a reliable way to evaluate ActiveAdmin theme compatibility across Rails upgrades without turning your application into a screenshot-only test suite?

AI assistance disclosure

AI assistance was used to organize this tutorial and check the Markdown structure. Repository facts, commands, limitations, and the documented Ruby example were checked against the public project sources linked above; no claim of a full Rails application run is made here.

Edit Currículo Lattes XML Safely with TypeScript and lattes-toolkit

Fernando Paladini — Tue, 03 Nov 2026 12:32:40 +0000

If you maintain a Currículo Lattes, a small correction can become a fragile manual task: export the file, find the right XML element, edit it without breaking the document, and remember what changed before importing it again.

This tutorial shows a safer local workflow with lattes-toolkit. We will use the stable v2.4.0 release to read an exported XML file, change one typed field, preserve a backup, and verify the result before the human-controlled import step.

TL;DR

@paladini/lattes-toolkit is a TypeScript library and CLI for working with XML that you already have. It does not log in to Plataforma Lattes, download a curriculum, or click Import XML for you. That boundary is useful: the file stays local, and the final review remains explicit.

The core workflow is:

Export your XML from Plataforma Lattes.
Parse and inspect it locally.
Apply a narrow change.
Confirm the generated XML and keep the automatic backup.
Review and import the file manually.

The CNPq description of Plataforma Lattes explains the platform's role in Brazilian research information. The toolkit is an independent project and is not affiliated with CNPq.

Prerequisites

You need:

Node.js 18 or later.
An XML or ZIP export that you are allowed to edit.
A terminal and a text editor.
A separate copy of the original file before experimenting.

This tutorial is pinned to @paladini/lattes-toolkit@2.4.0, released from the repository's v2.4.0 tag. Pinning the version makes the commands reproducible even if npm's latest dist-tag moves later.

Install the pinned CLI

You can install the package in a project or invoke its CLI with npx:

npm install @paladini/lattes-toolkit@2.4.0
npx @paladini/lattes-toolkit@2.4.0 --help

The package declares Node.js >=18.0.0, uses the MIT license, and exposes the lattes-toolkit command. The help output is the quickest way to check that the expected CLI is available:

Usage:
  lattes-toolkit init [dir]
  lattes-toolkit parse <file.xml|zip> [--json|--summary]
  lattes-toolkit get <file> <path>
  lattes-toolkit set <file> <path> <value>
  lattes-toolkit serialize <file.json> -o <out.xml>
  lattes-toolkit backup list [dir]
  lattes-toolkit restore [--last|<backup-id>] [dir]
  lattes-toolkit validate <file.xml> [--dtd [file.dtd]]
  lattes-toolkit patch <file.xml> <patches.json>

Inspect an exported curriculum

Export your curriculum through the normal Plataforma Lattes interface and save it as curriculo.xml. Do not place a real curriculum in a public repository or issue. It contains personal data.

Start with a summary:

npx lattes-toolkit@2.4.0 parse curriculo.xml

If you need a particular field, use dot and bracket notation. For example, this reads the first journal article title:

npx lattes-toolkit@2.4.0 get curriculo.xml bibliographicProduction.journalArticles[0].title

The field names come from the toolkit's typed model, not from a guess about raw XML capitalization. The repository documents CLI commands and typed field coverage.

Make one narrow edit

Suppose the summary needs a correction. Use set with the exact path and value:

npx lattes-toolkit@2.4.0 set curriculo.xml identification.summary "A corrected professional summary."

The command serializes the XML back to the same path. When that destination already exists, the toolkit creates a snapshot under .lattes-backup/ before overwriting it. The backup documentation describes the manifest, SHA-256 value, retention behavior, and restore commands.

List the available snapshots:

npx lattes-toolkit@2.4.0 backup list

If the result is not what you expected, restore the latest snapshot before trying again:

npx lattes-toolkit@2.4.0 restore --last

For multiple edits, prefer patch with an allowlist rather than giving an automated process unrestricted access to the document:

{
  "allowlist": ["identification.summary"],
  "patches": [
    {
      "path": "identification.summary",
      "value": "A corrected professional summary."
    }
  ]
}

Save that as patches.json, then run:

npx lattes-toolkit@2.4.0 patch curriculo.xml patches.json

An allowlist is a practical safety boundary. It makes the intended edit reviewable and prevents a broad instruction from silently changing unrelated sections.

Verify before import

Read the edited field again:

npx lattes-toolkit@2.4.0 get curriculo.xml identification.summary

The package also includes an XSD-based validation command. It uses xmllint when that tool is available in your environment:

npx lattes-toolkit@2.4.0 validate curriculo.xml

Validation is not a promise that the Plataforma Lattes interface will accept every file. The project's documentation explicitly describes XSD and optional local DTD checks as environment-dependent, and says that schema validation does not guarantee platform acceptance.

For a programmatic workflow, the same boundaries are available in TypeScript:

import { readFileSync } from "node:fs";
import {
  applyCurriculumPatches,
  readCurriculum,
  writeCurriculum,
} from "@paladini/lattes-toolkit";

const curriculum = await readCurriculum(
  readFileSync("./curriculo.xml"),
);

applyCurriculumPatches(
  curriculum,
  [{ path: "identification.summary", value: "A corrected professional summary." }],
  { allowlist: ["identification.summary"] },
);

await writeCurriculum(curriculum, "./curriculo.xml");

After writing, parse the file again and inspect the changed field. Then open the XML in the Plataforma Lattes interface, review it, and perform the import yourself. The toolkit does not automate login or submission.

Why this workflow is safer

The library models supported fields as typed data, while retaining unmapped document content during the XML round trip. That is more deliberate than using a regular expression over XML text. The set command is useful for one field, while patch makes a batch change auditable through a JSON file.

Automatic snapshots address a different risk: editing the right field but disliking the result. The backup is local and should be excluded from Git with .lattes-backup/ in .gitignore.

The release history also matters. Version 2.0.0 introduced breaking model and serialization changes aligned with the repository's versioned XSD. Version 2.4.0 added typed technical-production fields. Pinning a release avoids accidentally mixing this tutorial with a future CLI or model change.

Failure modes and limits

The field path is wrong

A path that is not present in the typed model will not produce the intended update. Start with parse, consult the field coverage documentation, and make one small change at a time.

`xmllint` is unavailable

The validation command can report that validation was skipped when the required executable or local DTD is missing. Treat that as a missing verification step, not as proof that the file is valid.

The platform rejects the import

The toolkit cannot guarantee acceptance by Plataforma Lattes. Keep the original export, inspect the backup, and use the platform's own error message and documentation. Do not use the library to bypass a CAPTCHA, terms of use, or a required manual review.

Personal data leaks

Curricula contain personally identifiable information. Work on local copies, do not upload real XML to chat or public issue trackers, and use synthetic or anonymized fixtures for tests. The project explicitly says it does not download a curriculum from the public web or query a CPF.

FAQ

Does this package edit the online curriculum directly?

No. It edits an XML or ZIP file that you already have. Export and import remain manual.

Can I use it with an AI agent?

Yes, but give the agent a narrow allowlist, require a re-parse after writing, and keep the import step under human control. The repository has an AI-agent integration guide.

Does `validate` prove the import will work?

No. It can check against the packaged XSD when xmllint is available. Platform acceptance has additional behavior outside the toolkit's control.

Is this an official CNPq package?

No. It is an independent MIT-licensed project and states that it is not affiliated with CNPq.

Takeaway

Treat a Currículo Lattes export as a local, reviewable data file: pin the tool version, change only named fields, keep automatic snapshots, validate when possible, and import manually after checking the generated XML. That gives you repeatable edits without pretending that a local parser can replace the platform's own review and submission controls.

Have you found a useful field-level Lattes workflow that benefits from an allowlist and a generated backup?

AI assistance disclosure: I used AI assistance to organize and draft this tutorial. The commands, version details, project behavior, limitations, and links were checked against the paladini/lattes-toolkit v2.4.0 sources and a pinned CLI smoke test before publication.

Find Missing Loading and Error States in Next.js with unhappypath

Fernando Paladini — Sun, 01 Nov 2026 12:38:09 +0000

AI coding tools are good at making the successful path visible quickly. They can produce a page that loads data, accepts a form, and responds to a button click while leaving the slower, empty, failed, or repeated paths unfinished.

That gap is easy to miss in a screenshot. It is also expensive to find manually across every route and component. unhappypath is a small open-source CLI that scans source code for several of these missing UI states. It does not run a browser or call an LLM. It produces a repeatable score and findings that point to files, lines, and rule IDs.

This tutorial uses the current main source at commit 0827ee0. The repository currently reports version 0.1.0 in package.json, requires Node.js 20 or newer, and is licensed under MIT. There is no public release or tag, so the commands below describe the current repository state rather than a stable release.

TL;DR

Clone the repository, install its dependencies, build it, and scan a project directory:

git clone https://github.com/paladini/unhappypath.git
cd unhappypath
npm ci
npm run build
node dist/cli.js /path/to/your-next-app

The result includes a score from 0 to 100, four dimension scores, and findings such as RTE-01 for a missing loading boundary or QRY-02 for a query without visible error handling.

Prerequisites

You need Git, Node.js 20 or newer, npm, and a local Next.js or React project to inspect. The scanner reads source files from disk. It does not need a running development server, a database, API credentials, or network access after dependencies are installed.

The project depends on TypeScript for its build and uses Node's built-in test runner. Its package metadata declares MIT licensing and the CLI entry point as dist/cli.js.

Build the scanner from source

The repository documents npm ci followed by npm run build. Run those commands from the repository root:

npm ci
npm run build

After the build, the executable is available at dist/cli.js. The package also exposes an unhappypath binary when installed as a package, but building from source makes the inspected commit explicit.

Run the project's tests before using it in a workflow:

npm test

In the current checkout, this completed successfully with 18 tests. The test command builds first and then executes the compiled tests, so a successful result covers both the TypeScript compilation and the repository's fixture contracts.

Scan a project

Point the CLI at the directory that contains the application source:

node dist/cli.js /path/to/your-next-app

The path is positional. If you omit it, the CLI uses the current directory. For a machine-readable report, add --json; for a Markdown report, use --markdown. To make the command fail when the score is below a threshold, use --min-score:

node dist/cli.js . --json --out unhappypath-report.json --min-score 75

The CLI documents exit code 0 for a successful scan, 1 when --min-score is not met, and 2 for a usage error. A threshold is a policy choice, not a claim that the application is production-ready. The scanner only checks the signals implemented by its rules.

Use the built-in fixtures to understand the output

The repository includes a deliberately incomplete project and a project with the expected boundaries. Run both demos:

npm run demo:broken
npm run demo:good

The broken fixture currently reports 38/100 and 14 findings. It includes missing route boundaries, a query without loading, error, or empty handling, a form without pending feedback, a fetch effect without loading and error state, and an asynchronous click without a disabled or pending state.

The good fixture reports 100/100 and zero findings. That is useful for checking the command and output format, but it is not evidence that an arbitrary application has complete UX coverage. The fixture is intentionally shaped around the scanner's current heuristics.

Read findings as repair guidance

The rule IDs are stable within the repository's documented ups-v1 reference. Route checks include:

RTE-01: a route page has no loading boundary in its segment or ancestors.
RTE-02: a route has no not-found.tsx boundary in its segment or ancestors.
RTE-03: a route has no error.tsx boundary in its segment or ancestors.
RTE-04: the application has no root global-error.tsx.

For data and interaction code, query rules look for loading, error, and empty branches. Mutation rules look for pending feedback and empty catches. Form rules look for submitting or disabled behavior. A finding includes a file and line so you can inspect the source rather than guessing what the scanner saw.

The repository's recommended repair order is routes, queries, mutations, and forms. For example, a Next.js route can inherit an app/loading.tsx, while a query component should expose loading, error, and empty states near the query result. A scanner finding is a prompt to review the code, not an automatic patch.

Add a conservative CI gate

The README documents a GitHub Actions composite action as well as a direct npx example. A minimal workflow step is:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 20
- run: npx unhappypath . --min-score 75

The current repository's action.yml invokes npx --yes unhappypath@0.1.0 and accepts path, min-score, and format inputs. If you use that action, review the pinned version and its source before trusting it in a production workflow. The repository also documents the composite action form:

- uses: paladini/unhappypath@v1
  with:
    path: .
    min-score: "75"

The two examples have different versioning behavior. The direct command from the README uses the package name without a version, while the composite action currently calls 0.1.0. Check the project's release status before adopting either form. At the time of this tutorial, no GitHub release or tag was published.

Why this is useful, and where it stops

The scanner combines two kinds of static checks. A route scanner inspects Next.js App Router files such as page.tsx, loading.tsx, error.tsx, and not-found.tsx. A code scanner uses the TypeScript AST to inspect patterns such as query hooks, fetch calls inside effects, asynchronous click handlers, and forms.

That design makes the result deterministic and local. The same source tree can produce the same report without model tokens or external service availability. It also means the tool cannot prove runtime behavior. It does not run a browser, simulate a slow network or a server error, judge the quality of copy, or replace end-to-end tests. Its documented blind spots include deeply nested child-component handling and limited analysis of asynchronous Server Components.

Security boundaries matter too. The scanner reads files from the path you give it and writes reports or badges only when you request those outputs. It does not claim to validate authorization, input handling, secrets, dependencies, or server-side security. Keep those checks in their appropriate tools and tests.

FAQ

Does it support every React framework?

Not according to the current documentation. Its route rules target the Next.js App Router, while its code rules inspect selected TypeScript and React patterns. Vue, Nuxt, SvelteKit, and Remix route conventions are listed as future work.

Does a score of 100 mean the UI is production-ready?

No. It means the current rules found no missing signals in the scanned source. A score does not evaluate visual design, copy, runtime failures, accessibility quality, performance, or business behavior.

Can I use it without installing the repository?

The README documents npx unhappypath /path/to/your-next-app as the future npm option. The current repository also provides a source checkout path that works today. Verify package publication and version availability before depending on an unpinned command.

Takeaway

unhappypath is most useful as an early, deterministic review pass after an AI-assisted implementation. Build it from a known commit, scan the application, inspect each finding, and combine the result with runtime tests and human review. Treat the score as a prioritized checklist rather than a proof of readiness.

What is the most valuable unhappy-path check for your team: route boundaries, data states, mutation feedback, or form submission behavior?

Disclosure: This article was prepared with AI assistance. The repository documentation, package metadata, current commit, public GitHub metadata, and local commands described here were checked before publication.

Add Local Developer Utilities to Any MCP Assistant with DevUtils

Fernando Paladini — Sat, 31 Oct 2026 12:31:49 +0000

AI assistants are useful at translating intent into actions, but small developer utilities are an easy place for an agent to guess. A guessed hash, a malformed JSON transformation, or a misunderstood JWT timestamp can waste more time than the original task.

DevUtils MCP Server provides a local set of 36 developer utilities through the Model Context Protocol (MCP). The server exposes hashing, encoding, ID generation, JWT inspection, JSON formatting, network calculations, and text utilities over standard input and output. The operations run locally and the project documents no external API dependency.

This tutorial installs the stable v1.1.0 release, connects it to an MCP client, verifies the transport with a real initialize request, and explains where the tool is useful and where it is not.

TL;DR

Run the server with Node.js 18 or newer:

npx -y devutils-mcp-server@1.1.0

Then add the same command to your MCP client configuration:

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

After restarting the client, it can call tools such as hash_sha256, json_validate, generate_uuid, cidr_calculate, and text_stats.

Prerequisites

You need:

Node.js 18 or newer. The project recommends Node.js 22 for its current development environment.
An MCP-compatible client such as Claude Desktop, Cursor, VS Code Copilot, or Windsurf.
Network access only for the first npx package download. The server itself uses stdio and is documented as having no external API dependency.

The commands below target the published v1.1.0 release. The repository default branch currently contains 1.1.1, so pinning the package version makes this walkthrough reproducible against the stable release that was checked.

Install and connect the server

The simplest path does not install a global package. npx downloads the requested package version and starts its executable:

npx -y devutils-mcp-server@1.1.0

An MCP server using stdio is not a traditional web service. It waits for JSON-RPC messages on standard input and writes protocol responses to standard output. That is why the client configuration names a command and arguments rather than a URL.

For Claude Desktop on Windows, the documented configuration file is %APPDATA%\\Claude\\claude_desktop_config.json. For a workspace-specific VS Code setup, use .vscode/mcp.json with the VS Code servers shape:

{
  "servers": {
    "devutils": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "devutils-mcp-server@1.1.0"]
    }
  }
}

Use the configuration shape required by your client. Claude Desktop, Cursor, and Windsurf use an mcpServers object in the project documentation, while VS Code uses servers and includes type: "stdio".

Verify the transport before using tools

You can verify the minimal path without opening a client. Send an MCP initialize request to the package:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0.0"}}}' | npx -y devutils-mcp-server@1.1.0

The expected result is a JSON-RPC response containing the negotiated protocol version and server information. The server may also write a short status message to stderr. That status line is separate from the JSON-RPC response and should not be parsed as a tool result.

The release smoke test returned this server identity:

{
  "name": "devutils-mcp-server",
  "version": "1.1.0"
}

If the command cannot find npx, check node -v and npm -v in the same environment used by your MCP client. GUI clients can inherit a different PATH from your interactive shell.

Use the tools for bounded operations

Once connected, ask the assistant for a small, inspectable operation. For example:

Use the DevUtils hash_sha256 tool on the exact string hello and return only the hexadecimal digest.

The server registers tools in eight groups. The release README lists six hash tools, eight encoding tools, four generators, two JWT tools, three formatters, five converters, two network tools, and six text tools. Names follow a predictable <domain>_<operation> pattern.

For structured data, a useful request is:

Use json_validate on this JSON and explain the error location if it is invalid: { "enabled": true, }

For network data, use a non-sensitive example:

Use cidr_calculate for 192.168.10.0/24 and show the network, broadcast, host range, and host count.

These examples are intentionally bounded. The model chooses an explicit tool and supplies typed arguments, while the server performs the utility operation and returns text. You still need to inspect the result when it matters.

Why the MCP boundary helps

The value is not that a local library becomes faster through MCP. Native libraries are usually the right choice inside application code. The value is that an MCP client can call a consistent, typed operation during a multi-step conversation without inventing an implementation.

DevUtils uses the official TypeScript MCP SDK, Zod schemas for tool inputs, and stdio transport. The source registers each tool category with an McpServer before connecting a StdioServerTransport. That keeps the boundary explicit: the assistant can request a named operation, but it does not receive arbitrary code execution through this server.

The repository also keeps the package small enough to understand. The source is organized under src/tools/ by category, including hash.ts, formatters.ts, network.ts, and text.ts. That structure makes the project useful as a reference when you want to learn how a TypeScript MCP server wires schemas and handlers together.

Important limitations and security boundaries

DevUtils is a utility server, not a general security oracle.

The jwt_decode and jwt_validate tool descriptions explicitly say that they do not verify a JWT cryptographic signature. Decoding a token can help inspect its header and payload, but it does not prove that the token was issued by a trusted authority. Never treat a decoded payload as authenticated.

Hashing tools also have different purposes. MD5 and SHA-1 are available for compatibility and checksums, not for password storage. For passwords, use a dedicated password hashing scheme and an appropriate work factor. DevUtils includes bcrypt operations, but its presence does not remove the need to manage credentials, secrets, and authentication policy correctly.

The server runs locally through stdio and the security policy says it does not expose HTTP endpoints or send user data to external services. That is a useful boundary, not a universal privacy guarantee. The MCP client still receives the inputs you give it, npx still downloads a package before first use, and your machine still controls the process environment. Review the package, lock down client permissions, and avoid sending secrets in casual prompts.

The project is also not the best choice for every workload. If application code needs a hash, JSON parser, or CIDR calculation, use the native library directly. MCP adds a process and protocol boundary, which is valuable for agent workflows but unnecessary for a tight application loop.

FAQ

Does the server need an API key?

No API key is required by the documented package configuration. The server is started locally with Node.js and uses stdio.

Does it work with every AI assistant?

It works with MCP-compatible clients. The README documents Claude Desktop, Cursor, VS Code Copilot, Windsurf, Docker, and other MCP clients. A client without MCP support cannot use this server through the documented path.

Should I use the unpinned `npx devutils-mcp-server` command?

You can follow the README's short command, but a pinned version is better for a reproducible setup. Recheck the current release before upgrading.

Is JWT validation cryptographic verification?

No. The documented jwt_validate operation checks structure, JSON, expiration, and signature presence. It does not verify the signature against a key.

Takeaway

DevUtils MCP Server is a practical way to give an MCP-compatible assistant a small, local toolbox with explicit names and typed inputs. Start with the pinned v1.1.0 command, verify the initialize response, and then try one bounded operation such as JSON validation or SHA-256 hashing.

Have you found a developer utility that an AI assistant repeatedly gets wrong and that would benefit from a typed MCP tool?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version details, configuration examples, and security boundaries were checked against the project's public documentation, source, release metadata, and a live initialize smoke test.

Build a Test-Gated Manifest V3 Extension for Safe X Tab Automation

Fernando Paladini — Fri, 30 Oct 2026 12:35:40 +0000

Automating actions in a social timeline is easy to start and surprisingly hard to bound. A browser extension can click the wrong control, run while you are away from the tab, request more permissions than it needs, or hide its failure mode behind a vague counter.

This tutorial uses X Likes Automator, a small open-source Manifest V3 extension, to show a more reviewable path. You will install the stable v1.1.0 release, inspect the permission boundary, run the repository's 171-test suite, and configure a deliberately conservative first session.

The goal is not to promise safe or compliant automation. The project warns that automated likes can conflict with X rules and may lead to rate limits, restrictions, or suspension. Treat the extension as an educational, personal-use example and stop if X shows an automation warning.

What you will build

You will load an unpacked browser extension into a Chromium browser and use it only in an X tab where you are already signed in. The extension reads visible posts, selects an eligible Like control, and pauses when the tab or window is not active.

The important design choice is the narrow surface: the extension is not a login client and does not use an X API token. Its manifest requests storage plus host access for https://x.com/* and https://twitter.com/*. The repository's security tests also assert that cookies, passwords, session tokens, and unrelated sites are not collected.

Prerequisites

Chrome, Brave, or Microsoft Edge with Manifest V3 support.
A normal browser tab already open at X, with an account you control already signed in.
Node.js 20 or newer if you want to run the tests. Node is not required to run the unpacked extension.
A clone or the official v1.1.0 release archive.

Do not paste credentials into the repository or into the extension. Do not use a browser profile that contains accounts you are not authorized to operate.

1. Verify the release locally

Clone the exact stable tag instead of relying on the moving default branch:

git clone --branch v1.1.0 --depth 1 https://github.com/paladini/x-likes-automator.git
cd x-likes-automator

The tag is the reproducibility anchor for this tutorial. The README and release page identify v1.1.0, while the license file identifies the project as MIT.

Run the included checks:

npm test

The release currently reports 171 passing tests covering the manifest, permissions, settings, visible-page behavior, pause and resume rules, refusal list, localization, documentation, and policy engine. A green run does not prove that X accepts automated activity. It only checks the tagged project behavior.

2. Load the extension without a build step

Open the extensions page for your browser. In Chrome, the documented address is chrome://extensions; the equivalent pages are brave://extensions and edge://extensions.

Enable Developer mode.
Click Load unpacked.
Select the cloned x-likes-automator directory.
Confirm that the selected directory contains manifest.json at its top level.

The repository deliberately has no bundling step. Loading the source directory makes the reviewed JavaScript, manifest, popup, icons, and tests visible. If the browser reports a manifest error, stop and inspect the selected directory instead of downloading a random replacement archive.

Pin X Likes Automator in the browser toolbar, then open https://x.com/home in a regular tab. The extension does not open a new window or perform a login flow.

3. Configure a conservative first session

The popup is localized in Brazilian Portuguese. The setting names below are the behavior documented by the release:

Setting	`v1.1.0` behavior
Interval	Integer from 1 to 60 seconds; default 5 seconds
Interval jitter	A 5-second setting chooses a delay from 4.25 to 5 seconds
Optional cap	1 to 1,000,000 when enabled; default stored cap is 100
Original post in a reply thread	Enabled by default
Plain repost	Enabled by default, but can be turned off

For a first review, set the interval to 60 seconds, enable a cap such as 5, and turn off Repostar também. This keeps the session focused on the Like path and gives you a short, observable run. The cap is a control for your account activity, not a guarantee of compliance.

Press Iniciar while the active tab is an X home timeline, profile, search result, or single-post thread. If the active tab is another site, the project refuses to start.

4. Observe the policy boundary

The extension separates decisions from DOM operations. lib/policy.js is a pure decision engine that validates settings, classifies the current X surface, chooses the next eligible post, and decides whether to like, scroll, wait, pause, or stop. content/content.js adapts those decisions to the page.

That separation gives you useful review points. The extension should pause when the document is hidden or the window loses focus. It should skip a post that is already liked, remember a post within the current session, and refuse unsupported pages such as messages, settings, notifications, and compose screens.

The project also keeps an explicit refusal list. It does not click reply, quote, follow, direct message, login, or cookie controls. When the optional repost behavior is enabled, it only targets the plain repost menu item and never opens a composer.

If X displays an unusual-activity notice, the documented behavior is to wait 60 seconds and resume. The extension does not attempt to bypass that protection. You should still stop the session if the notice repeats or if the account's activity looks unexpected.

5. Verify the result and stop cleanly

During a small capped run, check the popup counter against the visible page. Switch away from the X tab and confirm that the status changes to paused. Return to the tab and confirm that the same session count resumes. Then click Parar before investigating anything else.

The repository documents a five-minute page reload cycle that preserves the session count through browser storage. A browser restart clears the volatile run state, so starting again requires an explicit button press. These details matter because a persistent background worker would have a different risk profile.

After stopping, inspect the browser's extension details and the repository's manifest.json. The expected permission shape is small:

{
  "permissions": ["storage"],
  "host_permissions": ["https://x.com/*", "https://twitter.com/*"]
}

This snippet is a review aid, not a complete manifest. Compare it with the actual release file rather than replacing the file with a hand-written version.

Failure modes worth checking

The popup says the tab is unsupported. Navigate to the X home timeline, a profile, a search result, or a thread. The extension intentionally ignores messages, notifications, settings, explore, compose, and non-X pages.

The session stays paused. Make the X tab visible and focus the browser window. The pause is presence-based by design.

The session does not start after installation. Reload the X tab and press Iniciar again. A tab that existed before installation may not yet have the content script.

The browser shows an automation warning. Do not increase the rate or try to evade the warning. Stop the session, review the account impact, and consult X's current rules.

The test suite fails. Do not treat a partial result as release validation. Check the Node version, rerun npm test from the tagged checkout, and compare the local files with the official release.

Security and privacy boundaries

The extension's narrow permissions reduce exposure, but they do not remove the central risk: it acts on a signed-in social account. The project cannot guarantee that a selector will remain correct as X changes its interface, and it cannot guarantee that automated activity is allowed for your account.

Review the security policy before reporting a vulnerability. Keep the account logged in only in a profile you control, use a small cap, keep the interval conservative, and remove the unpacked extension when you finish evaluating it.

FAQ

Does it need an X API key?

No. The documented design uses the open X tab and does not request an API token or credentials.

Does it run on every website?

No. The manifest host permissions and content-script matches are limited to X and Twitter origins.

Is a passing test suite a safety guarantee?

No. It verifies repository behavior at the checked-out release. It cannot predict policy enforcement, account restrictions, or future changes to X's DOM.

Can I make it run unattended?

The project is designed around an active, visible tab and pauses when the tab is inactive. Do not treat its reload behavior as permission to leave account automation unattended.

Takeaway

The useful lesson in X Likes Automator is not that social activity can be automated. It is that a browser extension becomes easier to review when its release is pinned, permissions are explicit, decisions are tested, unsupported actions are refused, and stopping behavior is visible.

If you try the tagged release, keep the first session small and verify each state transition yourself. Which boundary would you want to see tested before trusting a browser extension that acts on a signed-in account?

Disclosure: AI assistance was used to organize and edit this tutorial. The repository behavior, release metadata, documentation, license, configuration, and test result described here were checked against the public v1.1.0 sources.

Run OpenFold Locally: A TypeScript Simulator for Spatial Reasoning

Fernando Paladini — Thu, 29 Oct 2026 12:30:29 +0000

If a spatial-reasoning exercise uses a fixed image bank, repetition can become a memory test instead of a reasoning test. OpenFold takes a different approach: it generates cube-net folding problems locally, renders them in a web interface, and stores training history in the browser.

This tutorial shows how to run the current OpenFold repository, verify its build and test path, and understand what the project actually guarantees. The result is a local development server for an offline educational simulator, not a hosted account or a claim that the exercises measure intelligence.

TL;DR

OpenFold is a TypeScript monorepo owned by Fernando Paladini and licensed under the MIT License. It uses React, Vite, Three.js, Recharts, and IndexedDB to train mental rotation and spatial visualization with procedurally generated cube-net exercises.

The current repository state requires Node.js 20 or newer and pnpm 10. The minimal path is:

git clone https://github.com/paladini/OpenFold.git
cd OpenFold
pnpm install --frozen-lockfile
pnpm -w build
pnpm --filter @openfold/web dev --host 127.0.0.1

Open http://127.0.0.1:5174/ after Vite starts. OpenFold is offline-only in the documented current state. There is no cloud sync or user account.

Prerequisites

You need Git, Node.js 20 or newer, and pnpm 10. The repository's root package.json declares the Node engine and pins pnpm through its packageManager field. The workspace file includes packages/* and apps/*, so the install command must run from the repository root.

The repository's default branch is main. At the time of this tutorial, I verified commit d4035d8. The README mentions v1.0.0, but that tag and release are not available in the public GitHub releases endpoint. Treat this tutorial as a verification of the current default branch, not as instructions for a stable published release.

Install the workspace

Clone the repository and install the exact dependency graph recorded in pnpm-lock.yaml:

git clone https://github.com/paladini/OpenFold.git
cd OpenFold
pnpm install --frozen-lockfile

The --frozen-lockfile flag makes the first check useful. It prevents pnpm from silently changing the lockfile while you are trying to reproduce the project state. On the verified machine, the install completed with pnpm 10.33.3 and Node.js 24.15.0.

The current root manifest is private and reports version 0.0.0. That is another reason not to describe this checkout as an installed v1.0.0 package. The web workspace package is private and reports version 0.1.0.

Build the web application

Run the root build script:

pnpm -w build

The root script builds the workspace packages and applications. In the verified checkout, TypeScript compilation completed for the core and render packages, and Vite produced the web bundle for @openfold/web.

Vite reported a chunk-size warning for the generated JavaScript bundle. That is a build warning, not a failed build. It is worth keeping in mind if you later turn this educational project into a production web deployment, but it does not prevent local use.

Start the simulator

Start the documented web package directly:

pnpm --filter @openfold/web dev --host 127.0.0.1

The current Vite configuration sets port 5174. Visit http://127.0.0.1:5174/ in a browser. I verified that the development server returned HTTP 200 and that the response contained the OpenFold page title.

The interface is organized around training rounds, explanations, history, and settings. The repository describes three preset difficulty tiers and guided lessons for opposition and orientation rules. These are application behaviors described by the current source and tests, not an adaptive assessment or a clinical instrument.

Verify the project instead of trusting the page

OpenFold includes tests for the mathematical core, rendering behavior, and web application. Run them from the root:

pnpm -w test

In the verified checkout, the command passed 452 tests:

112 tests in packages/core.
76 tests in packages/render.
264 tests in apps/web.

The core tests check properties such as valid generated nets, distinct distractors, rotation-equivalent solutions, and seeded generation behavior. The render tests compare the visual fold state with the core model. The web tests cover rounds, explanations, IndexedDB persistence, exports, and several integration paths.

That distinction matters. A passing test suite supports confidence in the checked invariants and workflows. It does not prove that every browser, screen reader, GPU, or operating system behaves identically.

Why procedural generation helps

The README describes 11 canonical cube nets and a deterministic pseudorandom generator. Instead of selecting one image from a finite static bank, the core package can generate a problem from a seed, construct alternatives, and verify the folding relationship.

This design gives the project two useful properties. First, the exercise set is not limited to a small collection of screenshots. Second, a failing case can be investigated with a reproducible seed. The tests use that property to sweep many seeds and check invariants rather than relying only on a few hand-written examples.

The web application keeps telemetry and training history locally with IndexedDB. Recharts is used for charts, while Dexie provides the browser database layer. The local storage boundary is explicit: the current project does not provide cloud synchronization, accounts, or a server API.

Common failure modes

The wrong package manager

If pnpm is missing or the version is too old, installation can fail before the workspace is linked. Check the root package.json and use pnpm 10 rather than substituting npm commands. The repository is structured as a pnpm workspace.

Running from the wrong directory

The root scripts use workspace filters. Running them from apps/web changes the context and can make the command appear to be missing packages. Start in the directory that contains pnpm-workspace.yaml.

Mistaking a warning for a failed build

Vite may warn about a bundle larger than 500 kB. Read the final exit status and the generated output. A warning deserves a future optimization task, but it is different from a compilation or test failure.

Expecting saved history on another device

Training data is stored in the local browser. Clearing site data, changing browsers, or moving to another machine can remove access to that history. The project includes export-related code, but it does not currently provide remote backup or synchronization.

Security and privacy boundaries

The current README describes an offline-only application with no network calls during training and no user accounts. That reduces the data-sharing surface for local practice, but it is not a security guarantee for every dependency or future build.

Review the dependency lockfile before distributing a build. Use the source and lockfile from a known commit, keep browser permissions narrow, and do not treat locally stored telemetry as encrypted evidence. If you add cloud sync, authentication, analytics, or a hosted API, those changes require a new threat model and a new privacy review.

The MIT license permits reuse with the conditions stated in LICENSE. It does not provide a warranty, and OpenFold should not be presented as medical, psychological, or employment advice.

FAQ

Does OpenFold need an internet connection while I train?

The documented current design is offline-only after download. You need network access to clone the source and install dependencies, but the application itself is designed to run locally.

Can I use it as an adaptive assessment?

No. The current README explicitly describes deterministic difficulty tiers rather than adaptive IRT. It is an educational simulator for practice, not a validated assessment.

Is there a desktop installer?

The repository contains a Rust desktop wrapper, but the current README lists portable binaries and no native installers as a limitation. The commands in this tutorial run the web application.

Can I add another language?

The README says the structure is ready for translations, while the current application is English only. Adding localization would require implementation and verification work; it is not enabled by the commands above.

Takeaway

OpenFold is a useful example of a local-first learning tool: procedural generation supplies reproducible exercises, the rendering layer visualizes the fold, and IndexedDB keeps training history in the browser. The reliable way to evaluate it is to pin a commit, install with the frozen lockfile, run the build and tests, then inspect the local Vite application.

What would you value most in a next iteration: more spatial problem types, localization, or an explicitly designed export and backup workflow?

Disclosure: AI assistance was used to organize and edit this tutorial. The repository claims, commands, version details, and verification results were checked against the cited public sources and a fresh checkout of the current main commit.

Run a Zero-Dependency Security Awareness Quiz with HTML, CSS, and JavaScript

Fernando Paladini — Tue, 27 Oct 2026 12:39:23 +0000

Security training pages often become harder to maintain than they need to be. A small internal learning site may not need a framework, a database, or a build pipeline. It needs clear content, a few interactive checks, and a local workflow that people can inspect before the site is hosted.

This tutorial uses Guardiões da Segurança Digital, a public static project by Fernando Paladini. The repository contains one HTML document, one JavaScript file, one stylesheet, and a license file. Its documented scope is security awareness: fundamentals, asset protection, threats, defensive habits, compliance topics, and an interactive quiz.

The goal is practical: clone the repository, serve it locally, verify the page and its assets, and understand what the code does before adapting it for a team. The result is a local training site that can be reviewed without installing a JavaScript package.

TL;DR

Clone the repository, run Python's built-in static server from the project root, and open http://127.0.0.1:8000. The page loads index.html, script.js, and style.css directly. The quiz state lives in the browser, so this project does not collect answers or provide a server-side training record.

Prerequisites

You need:

Git
Python 3, only for the local HTTP server
A modern browser
A terminal with permission to create a temporary local checkout

There is no package.json, dependency lockfile, bundler, or database in the current main branch. The repository does not publish a tagged release, so the commands below target the current documented branch rather than a versioned package.

1. Clone and serve the project

Use a temporary directory when reviewing the project. This keeps the experiment separate from any local source tree.

git clone https://github.com/paladini/guardioes-da-seguranca-digital.git
cd guardioes-da-seguranca-digital
python3 -m http.server 8000 --bind 127.0.0.1

Open http://127.0.0.1:8000 in your browser. The repository's actual root contains index.html, script.js, and style.css, so serve the root directory. The README currently shows an older ad1 path and a different clone name. The root layout is the reliable example for the current main tree.

Python's http.server module is convenient for local review, not a production deployment. Python's own documentation warns that it implements only basic security checks. Bind it to 127.0.0.1 when you only need local access.

Stop the server with Ctrl+C when the review is complete.

2. Check the static application boundary

The page is intentionally easy to inspect. The HTML document defines the learning sections and the quiz container. The stylesheet provides the responsive layout, visual states, focus styles, and a reduced-motion media query. The JavaScript file initializes navigation, smooth scrolling, information modals, the quiz, and accessibility-related behavior.

You can confirm the asset links without opening developer tools:

curl -I http://127.0.0.1:8000/
curl -I http://127.0.0.1:8000/script.js
curl -I http://127.0.0.1:8000/style.css

Each request should return an HTTP success response while the local server is running. This checks delivery of the three files, not the quality of every visual or keyboard interaction.

The project also links to external Font Awesome and Google Fonts assets from the HTML document. That means the page is source-local but not completely network-independent in its default presentation. If the browser cannot reach those hosts, the core HTML, CSS, and JavaScript still provide the application structure, but icons or typography can look different.

3. Walk through the learning flow

The current page exposes sections for an introduction, security fundamentals, assets, threats, defense, and a quiz. The README describes ten quiz questions with immediate feedback. The JavaScript implements a start action, question display, option selection, feedback, next-question navigation, results, and restart behavior.

Review the page in this order:

Confirm that the main navigation reaches each section.
Open an information modal and close it with the visible control.
Start the quiz and select an option.
Confirm that the selected option receives a visual state and feedback appears.
Continue until the result screen, then use the restart action.
Repeat the flow with keyboard navigation and with reduced motion enabled in the browser or operating system.

This is a useful review pattern for static training content because it separates content delivery from interaction behavior. A page can look complete while a keyboard user cannot reach the same controls. Test both paths before sharing the URL with a team.

4. Verify the result reproducibly

For a lightweight smoke check, verify the files and the local response from the same checkout:

test -f index.html && test -f script.js && test -f style.css && test -f LICENSE
curl -fsS http://127.0.0.1:8000/ | grep -q "Guardiões da Segurança Digital"
curl -fsS http://127.0.0.1:8000/script.js | grep -q "startQuiz"
curl -fsS http://127.0.0.1:8000/style.css | grep -q "prefers-reduced-motion"
printf 'static smoke check passed\n'

On Windows PowerShell, the equivalent checks are:

Get-Item index.html, script.js, style.css, LICENSE
$html = Invoke-WebRequest http://127.0.0.1:8000/ -UseBasicParsing
$html.StatusCode
$html.Content.Contains('Guardiões da Segurança Digital')

The expected result is a 200 response and True for the title check. These checks do not replace manual browser testing, but they make the minimum path repeatable after a clone or a content change.

Why this architecture works for a small training site

The useful property is not that the project uses a particular framework. It is that the learning path is visible in ordinary web files. Content editors can find the HTML sections, visual changes stay in CSS, and interaction logic stays in JavaScript. There is no build output to regenerate and no package installation step that can hide the source of a behavior.

That simplicity also keeps the local review cheap. A reviewer can run the site with a standard Python installation, inspect the network requests, and disconnect the server without leaving a background service or a database behind. For a short awareness exercise, that is often enough.

The tradeoff is that the project has no built-in account system, progress persistence, analytics, content management interface, automated accessibility report, or server-side assessment. Treat it as a static learning resource, not as a compliance evidence platform.

Failure modes and security boundaries

The page is blank or scripts do not run

Check that the server is running from the repository root. Do not serve the parent directory and assume the browser will find the assets. Then inspect the browser console and confirm that the relative script.js and style.css requests return success responses.

The page looks different offline

The HTML references external Font Awesome and Google Fonts URLs. Offline use can therefore change icons and fonts. If the environment must work without a network connection, replace those assets with locally reviewed equivalents and test the resulting page.

The local server is exposed beyond the workstation

Use --bind 127.0.0.1 for a local review. Do not treat python3 -m http.server as an authenticated or hardened production server. If the content needs public hosting, use a deployment service with an appropriate security and caching configuration.

The license information is inconsistent

The README displays an MIT badge, but the current repository LICENSE file contains the GNU General Public License, version 3 text. Resolve that discrepancy with the project owner before redistributing modified copies or presenting the project as MIT-licensed. The license file, not a badge, is the source that needs legal review here.

FAQ

Does this project need Node.js?

Not for the documented local path. The current tree is a static HTML, CSS, and JavaScript site, and the smoke test uses Python's standard HTTP server.

Does the quiz store participant results?

No server-side storage is documented or present in the reviewed files. The interaction is browser-local and should not be described as an attendance or compliance record.

Can I publish it as-is for employee training?

Review the wording, external assets, accessibility behavior, privacy requirements, and license discrepancy first. Educational content about security is not a substitute for an organization's policies or professional security guidance.

Takeaway

A useful security awareness prototype can be a small, inspectable static site. Start the current repository from its root, verify the three delivered assets, test the quiz with both mouse and keyboard, and keep the local server bound to localhost. Before redistribution, correct the README-versus-license mismatch and decide whether a static quiz is enough for your evidence and privacy needs.

What would you add first to this static training flow: a content review workflow, a formal accessibility test, or an opt-in progress record with a clear privacy policy?

AI assistance disclosure: AI helped organize and edit this tutorial. The repository files, commands, license discrepancy, and local smoke-test result were checked against the cited primary sources before publication.

Rewrite Git Commit Messages Safely with git-translate-commits

Fernando Paladini — Mon, 26 Oct 2026 12:37:00 +0000

Mixed-language commit history is easy to create and hard to search. An AI coding assistant may write one commit in English, another in Portuguese, and a third with a Conventional Commit prefix that you still want to keep. The result is a history that is technically valid but less useful to humans and release tooling.

git-translate-commits is an open-source Python CLI for translating commit messages to a target language. Its default engine uses Argos Translate locally. It also has an optional LLM engine, but this tutorial stays on the local path so the example does not need an API key or a network request to a model provider.

The important part is not the translation command by itself. Rewriting commits changes commit IDs, so a safe workflow needs a preview, a backup, a narrow scope, and a clear recovery plan.

TL;DR

Install the release with pipx, preview a translation on a disposable clone, and only then run the rewrite on a repository you control:

pipx install git-translate-commits
git clone https://github.com/example/project.git project-copy
cd project-copy
git-translate-commits --lang en --dry-run
git-translate-commits --lang en

The command creates a backup branch by default before rewriting. Still, treat the operation as history surgery: coordinate with collaborators before force-pushing rewritten refs.

Prerequisites

You need:

Python 3.10 or newer. The stable v1.0.1 release declares requires-python = ">=3.10".
Git and a local clone with a clean working tree.
pipx, uv, or pip for installation.
A repository whose history you are allowed to rewrite.

The project is licensed under GPL-3.0-or-later. The release source and metadata are available at the v1.0.1 tag.

Install the stable release

The README recommends an isolated CLI installation with pipx:

pipx install git-translate-commits

You can use uv instead:

uv tool install git-translate-commits

For development or a one-off environment, plain pip is also supported:

python -m pip install git-translate-commits

Verify the installation through the executable and inspect the current options:

git-translate-commits --version
git-translate-commits --help

The v1.0.1 package metadata and the CLI version callback are not currently aligned: the package metadata declares 1.0.1, while the callback reports 1.0.0. That does not change the documented command surface, but it is worth recording when you verify the installation.

Preview a local translation

Do not begin with your only clone. Make a disposable copy, or clone the repository again for the preview:

git clone https://github.com/your-account/your-project.git history-preview
cd history-preview
git status --short
git-translate-commits --lang en --dry-run

The --lang option is required. The repository documents language codes such as en, pt-BR, es, fr, de, and ja. The default engine is local:

git-translate-commits --lang en --engine local --dry-run

On first use, Argos Translate may download language packs, which the project README describes as roughly 50 MB per pack. After the pack is available, the local engine is designed to run without an API key and without sending commit messages to an LLM provider.

Use the preview to answer three questions before changing anything:

Does the detected source language match the history you intended to process?
Do the proposed translations preserve the meaning of commit messages?
Is the repository scope narrow enough for this rewrite?

If the preview is too broad, add filters. For example, process one author or a date range:

git-translate-commits --lang en --author "dev@example.com" --dry-run
git-translate-commits --lang en --since "2025-01-01" --until "2025-12-31" --dry-run

Rewrite with a recovery branch

Once the preview is acceptable, create a separate working clone or confirm that you can restore the original refs. The default rewrite command is:

git-translate-commits --lang en

The project documents these default protections:

--backup is enabled, so a backup branch is created before changes.
--skip-already-translated is enabled, so messages already detected in the target language can be skipped.
--preserve-conventional is enabled, so prefixes such as feat:, fix:, and chore: are preserved.
Git trailers such as Co-authored-by and Signed-off-by are preserved.
Issue references such as #123 and JIRA-456 are preserved.

You can select branches explicitly instead of processing the current branch:

git-translate-commits --lang en --branch main
git-translate-commits --lang en --branch main --branch release
git-translate-commits --lang en --all-branches

Do not add --force until you understand the confirmation step. The flag skips confirmation, which is useful for automation but removes an intentional pause before a destructive history rewrite.

Verify the result

A successful command is not enough. Inspect the rewritten history and the generated log:

git status --short
git log --oneline --decorate -n 10
Get-ChildItem .git-translate-log.json
git branch --list

On Unix-like shells, the final command can be replaced with ls -l .git-translate-log.json. The project documents .git-translate-log.json as the JSON operation log containing the mapping of changes.

Then compare representative commits against the backup branch. Commit hashes must change when messages change because the message is part of each commit's identity:

git show backup-before-translation:README.md > $null
git log --format="%h %s" backup-before-translation -n 10
git log --format="%h %s" HEAD -n 10

The exact backup branch name is reported by the tool, so replace backup-before-translation with the name shown in your run. Check authors, timestamps, trailers, issue references, and file contents. The intended change is the commit message, not the tree.

Why the local path is useful

The local engine separates the basic workflow from provider credentials. That makes a dry run easier to reproduce and keeps ordinary commit text on the local machine after language packs are installed. It also makes the trade-off explicit: local neural translation may be less context-aware than an LLM translation, especially for project-specific terminology.

The optional LLM engine is a separate path. Install the extra dependency and configure a provider only when you have accepted the data handling and cost implications:

pipx install "git-translate-commits[llm]"
git-translate-commits --lang en --engine llm --provider openai --model gpt-4o-mini

The repository documents OpenAI, Anthropic, and OpenAI-compatible providers. It also recommends environment variables such as OPENAI_API_KEY and ANTHROPIC_API_KEY. Never put a real key in a commit message, shell history that you intend to share, or an article example.

Failure modes and limits

Commit IDs change

This is expected. A rewritten commit is a different object, so existing remote branches, pull requests, tags, and clones do not automatically follow it. Coordinate the force-push and ask collaborators to re-clone or carefully reset their local refs.

Translation quality is not guaranteed

The tool preserves selected structure, not intent. Review translations containing product names, legal terms, incident details, or specialized abbreviations. A preserved Conventional Commit prefix does not prove that the rest of the message is accurate.

Backups are local recovery aids

The automatic backup branch helps you recover from a local mistake. It is not a substitute for a verified remote backup, a release tag, or a team communication plan. Do not assume that a backup branch was pushed unless you explicitly verify it.

LLM mode changes the trust boundary

The local engine and the LLM engine are not equivalent. LLM mode can send commit text to the configured provider and can incur provider charges. Use the local mode for sensitive history unless your organization's policy allows the external provider path.

FAQ

Does this translate file contents?

No. The documented purpose is translating Git commit messages. Verify the working tree and representative file hashes if the history is business-critical.

Can I translate only recent commits?

Yes. Use --since and optionally --until, or filter by --author and --branch.

Can I avoid changing already English messages?

The default --skip-already-translated behavior is intended for that case. Review the dry-run output because language detection is not perfect.

Should I rewrite a shared public branch?

Only with agreement from everyone consuming it. A rewritten public branch creates coordination work even when the translated messages are correct.

Takeaway

git-translate-commits is most useful when treated as a controlled migration: preview on a disposable clone, use the local engine when privacy matters, keep the automatic backup, verify the log and commit metadata, and coordinate before updating shared refs. The translation is the easy part. The recovery and communication plan are what make the rewrite safe.

Have you standardized mixed-language commit history before, and would you prefer a local translation engine or a reviewed manual rewrite for a shared repository?

AI assistance disclosure

AI assistance was used to organize this tutorial and edit its prose. The repository documentation, stable release metadata, license, source behavior, and local test results were checked separately. The article does not claim that the AI ran a production history rewrite.

Sync Shared AI Guidance Across Repositories with team-ai-sync

Fernando Paladini — Sun, 25 Oct 2026 12:33:04 +0000

Teams often agree on a shared AGENTS.md, CLAUDE.md, prompt directory, or editor configuration, then discover that every repository has a slightly different copy. Manual copying is easy to start and hard to trust. A stale instruction can change how an AI coding agent edits a codebase, while a direct write to a default branch removes the review point that should catch the mistake.

This tutorial shows how to use team-ai-sync to keep shared AI guidance in one source repository and distribute it through reviewable pull requests. The example uses the stable v1 Action, a JSON configuration file, and a dry run before any branch or pull request is created.

TL;DR

Create a sync-config.json file that names target repositories and repository-relative paths. Call paladini/team-ai-sync@v1 from GitHub Actions with a token that can update the targets. Start with dry-run: true, inspect the result, then allow the Action to create or update pull requests. The tool does not merge those requests for you.

Prerequisites

You need:

A source GitHub 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 token with Contents: Read and write and Pull requests: Read and write on the targets. Issues: Read and write is also needed when the configuration applies labels.
A GitHub Actions workflow that can read the source repository.

The stable v1 Action runs on Node 24. The repository's v1 tag documents GitHub Actions, GitLab CI/CD, and Bitbucket packages, but this walkthrough focuses on GitHub.

1. Create the source configuration

Put the files that should be shared in the source repository. For example, this can be an AGENTS.md file plus instructions under .github/instructions.

Create sync-config.json beside those files:

{
  "targetRepositories": [
    "your-org/api-service",
    "your-org/web-app"
  ],
  "syncMode": "overwrite",
  "deleteOrphans": false,
  "files": ["AGENTS.md", "CLAUDE.md", ".editorconfig"],
  "directories": [".github/instructions", ".github/prompts"],
  "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": []
  }
}

The configuration requires at least one file or directory. overwrite replaces an existing configured path. Use skip when the first sync should install starter files without replacing local edits. Directories are copied recursively, and exclude accepts repository-relative paths or glob patterns.

Keep target names and paths intentional. The project validates paths before processing targets and rejects absolute paths, .. traversal, .git segments, and paths that resolve outside a repository root.

2. Add the workflow

Create .github/workflows/sync-ai-assets.yml in the source repository:

name: Sync AI Assets

on:
  push:
    branches: [main]
  workflow_dispatch:

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

Create the TEAM_SYNC_ADMIN_PAT repository secret in the source repository. The source workflow's GITHUB_TOKEN only needs to read the source checkout. The separate github-token input is the credential used to clone target repositories, push sync branches, and create or update pull requests.

The Action also accepts source-root and dry-run. The default configuration path is sync-config.json, so config-path is optional when you use that name.

3. Run a dry run first

Before opening pull requests, add the dry-run input:

- uses: paladini/team-ai-sync@v1
  with:
    github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
    config-path: sync-config.json
    dry-run: true

The dry run validates the configuration, clones targets into temporary worktrees, copies the configured paths, and reports whether changes exist. It does not push branches or create pull requests. This makes it the right first check for a new target list and for changes to deleteOrphans.

When the dry run is clean, remove dry-run: true or set it to false. A real run resolves each target's default branch, creates or resets the configured sync branch, copies files, commits only when changes exist, pushes the branch, and creates or updates one pull request per changed target.

Expected result

For each target with changes, the result should be a normal pull request from the configured sync branch. The generated request is where a target repository owner can review the exact file changes, discuss them, and decide when to merge.

The Action exposes JSON outputs for pr-urls, synced-targets, failed-targets, and changed. A later run with no differences should report changed=false for the no-change case. The project's public demo documents this lifecycle with a dry run, pull request creation, an update to existing requests, a merge, and a final no-change run.

Why this review boundary matters

The useful design choice is not only central storage. team-ai-sync keeps synchronization separate from approval. It creates or updates branches and pull requests, but it does not merge requests, bypass branch protection, approve requests, manage secrets, or change target repository settings.

That boundary supports a practical operating model: keep shared guidance in one source repository, let automation prepare changes, and let each target repository review the change in its own context. A repository can still reject an instruction that is inappropriate for its language, deployment model, or security requirements.

Security boundaries and failure modes

Treat the token as a write credential. Store it as a repository or project secret, grant access only to the targets that need synchronization, and never put it in sync-config.json or a committed workflow file.

Do not distribute private keys, credentials, or machine-specific settings. The project is designed for reviewable guidance, prompts, editor settings, and repository conventions. It cannot make a shared instruction safe merely because the file arrived through a pull request.

Be especially careful with deleteOrphans. It defaults to false. When enabled, deletion is limited to files inside configured synced directories, but it can still remove target files that are no longer present in the source. Run a dry run first and review the proposed changes.

A missing configured file or directory fails validation before pull requests are created. A target can fail independently while other targets continue, so inspect failed-targets rather than treating a successful workflow as proof that every repository changed. Cross-platform synchronization is not the supported operating model: use the GitHub Action for GitHub targets, the GitLab component for GitLab projects, and the Bitbucket pipe for Bitbucket repositories.

Reproducible verification

The v1 checkout of the repository was verified locally with the documented development commands:

npm ci
npm run lint
npm test
npm run build

The checks completed successfully: TypeScript linting passed, 6 test files with 18 tests passed, and the bundled Action build completed. npm ci also reported 9 dependency audit findings, including 7 high-severity findings, so that result is a dependency warning rather than a security guarantee.

To verify your own rollout, keep the first target set small. Compare the dry-run output with the source files, inspect the generated pull request, and confirm that the target branch contains only the configured paths. Then merge manually and run the workflow again to verify the no-change behavior.

FAQ

Does it merge pull requests automatically?

No. It creates or updates pull requests and leaves review, approval, and merge to target repository maintainers.

Can I sync only files that are missing?

Yes. Set syncMode to skip. The default overwrite mode replaces existing configured paths.

Can I remove stale files?

Set deleteOrphans to true only for configured synced directories. Review a dry run first.

Which files can I sync?

The documented examples include AGENTS.md, CLAUDE.md, Copilot instructions, prompt directories, Cursor rules, .editorconfig, and other repository-relative files or directories.

Does the Action need a secret?

Yes, when it must access target repositories. Use the github-token input with a suitably scoped PAT or GitHub App token stored as a secret.

Takeaway

Centralizing AI guidance is useful only when updates remain reviewable. team-ai-sync turns a shared-file problem into a normal branch and pull request workflow: validate paths, dry-run the target set, inspect the generated changes, and keep the final merge decision with each repository.

Have you found a better review policy for synchronizing AGENTS.md or prompt files across a repository fleet? Share the rule that has prevented the most drift in your team.

AI assistance disclosure

AI assistance was used to organize and edit this tutorial. The repository documentation, stable v1 examples, license, security model, and local verification results were checked against primary sources before publication.

Sources

Stop Guessing localhost Ports with portmap and TypeScript

Fernando Paladini — Sat, 24 Oct 2026 12:31:02 +0000

AI coding agents are very good at remembering common conventions. That is also why they can be very confident and completely wrong about localhost:3000.

One project may expose a Vite frontend on port 5173. Another may run an API on 8080. A Docker mapping can make the host port different from the container port, while an .env.local file may still point to a service that is not running today. The resulting error often looks like CORS, authentication, or a broken API client when the real problem is a stale URL.

portmap is a small MIT-licensed TypeScript CLI and read-only MCP server for this local-development problem. It combines declared configuration, optional OS listener data, and environment references into a .portmap.json report with findings such as PRT-04 for an environment URL that points at a port with no listener.

This tutorial uses the current repository configuration and the checked-in mismatch fixture. You will build portmap from source, run a deterministic static scan, inspect the generated findings, and understand where the tool deliberately stops.

TL;DR

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci
npm run build
node dist/cli.js declare fixtures/mismatch --json

The output identifies a declared Vite port and two unresolved localhost environment URLs. That gives an agent or a developer concrete evidence before changing application code.

Prerequisites

You need:

Node.js 20 or newer. The repository declares engines.node as >=20.
npm and Git.
A Windows, macOS, or Linux development machine for the documented runtime listener support. The static declare command does not need a running service.

The repository is public, non-archived, non-forked, and uses the MIT license. At the time of writing, the repository reports version 0.1.0 in package.json and does not provide a GitHub release, so the reproducible path below pins the source checkout by its current default branch rather than claiming a released package.

Build portmap from the repository

Clone the project and install the lockfile exactly:

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

The build runs TypeScript with the repository's tsconfig.json and produces the dist directory. The CLI entry point is dist/cli.js; the package metadata also exposes a portmap binary when the project is installed as a package.

The current README documents npm ci, npm run build, and node dist/cli.js as the source-based installation path. It also documents npx portmap as a future npm option, so do not use the latter as if a published npm package were already verified.

Run a static topology check

The safest first check is declare. It reads project files without requiring the application's processes to be running:

node dist/cli.js declare fixtures/mismatch --json

The fixture is intentionally broken. Its configuration declares a Vite server on port 5173, while .env.local contains references to http://localhost:3000 and http://localhost:8080. Because no matching service is declared for those references, the report contains unresolved environment edges.

The important part of the JSON is the relationship between the declared service, references, and findings:

{
  "services": [
    {
      "id": "vite",
      "declared": {
        "port": 5173,
        "sources": ["vite.config.ts:server.port"]
      },
      "status": "down"
    }
  ],
  "findings": [
    {
      "id": "PRT-01",
      "severity": "error"
    },
    {
      "id": "PRT-04",
      "severity": "error",
      "file": ".env.local:1"
    }
  ]
}

The complete report includes the second PRT-04 for the port 8080 reference. The fixture has no listener data because this static command does not inspect the operating system.

Use the result in a real project

Run declare against your application first:

node /path/to/portmap/dist/cli.js declare /path/to/your-app --json

If the report is useful as persistent agent context, write it to the project root:

node /path/to/portmap/dist/cli.js declare /path/to/your-app --write

This creates .portmap.json. The repository's schema documentation describes it as the artifact agents can read instead of guessing a URL. Whether you commit it is a project decision: committing it can make a known local topology available to future sessions, while ignoring it avoids storing machine-specific runtime data.

When processes are running, the full command adds an OS listener scan:

node /path/to/portmap/dist/cli.js scan /path/to/your-app --json

The full scan can report declared ports that are not listening, listeners without declared configuration, mismatched Docker host and container ports, and environment references that do not resolve. The README also documents workspace for projects in sibling folders and listen for inspecting listeners directly.

Add a read-only MCP server

portmap includes a read-only MCP stdio server. After building, the command is:

node /path/to/portmap/dist/cli.js mcp

For Cursor or Claude Code, the documented configuration points the MCP command at the built CLI:

{
  "mcpServers": {
    "portmap": {
      "command": "node",
      "args": ["/path/to/portmap/dist/cli.js", "mcp"]
    }
  }
}

The exposed tools are intentionally narrow: retrieve a full report, get a smaller service graph, resolve a URL, or filter findings. The server does not start or stop services, modify application files, or infer ports with an LLM.

Why the reconciliation is useful

The core design separates three kinds of evidence:

Declared configuration tells you what the project says should run. portmap looks at package scripts, Vite configuration, environment URLs, and common Docker Compose port mappings.
Runtime discovery tells you what the operating system says is listening. This is optional because a static check is still valuable before startup.
Reconciliation connects declarations, listeners, and environment references into services, edges, and findings.

That separation makes a failure actionable. PRT-04 means an environment URL points at a port with no listener, while PRT-02 warns about a listener without a corresponding declaration. Those are different repair paths, even though both can surface as a browser network error.

CI verification

The CLI can turn findings into a non-zero exit status. For example, this command fails when at least one error remains:

node dist/cli.js scan . --min-findings 1 --min-severity error --json

Use this as a local-development guard, not as production monitoring. The project is designed for local service topology and explicitly does not provide uptime or production health checks.

Failure modes and security boundaries

There are several important boundaries:

Runtime-only ports that are hardcoded in JavaScript without a discoverable configuration can produce a PRT-02 warning or remain undiscovered.
WSL and Docker networking can make a container listener invisible from the host perspective.
The current YAML Compose support handles common ports: patterns, not every Compose feature.
PID-to-repository attribution is heuristic. Low-confidence matches are flagged rather than presented as certain.
The MCP server is read-only, but a local MCP client still decides which project path to pass to it. Review client configuration and avoid exposing sensitive directories unnecessarily.

The tool reads local configuration and socket information. It is not a secret manager, a process supervisor, or a security guarantee. Keep .env values out of reports and repositories when they contain credentials; the useful signal is the referenced host and port, not the secret itself.

Reproducible verification

From the clean checkout, verify the source path and fixture again:

npm ci
npm run build
node dist/cli.js declare fixtures/mismatch --json > mismatch-report.json

Confirm that the JSON parses and contains PRT-01 plus the unresolved PRT-04 findings. For your own project, change one environment URL to the actual declared port, rerun the command, and compare the findings. That gives you a small, reproducible experiment instead of relying on whether an agent happens to guess correctly.

The repository also includes npm test, demo:mismatch, and demo:workspace scripts. In a clean Windows checkout, the build and static fixture declaration are useful smoke checks; if a runtime listener check behaves differently on your platform, treat that as an environment-specific result and inspect the generated report rather than assuming the listener model is universal.

FAQ

Does portmap replace Docker or a process manager?

No. It reports topology. It does not start, stop, or restart services.

Does it require an AI model?

No. The repository describes the scanner and MCP server as deterministic and zero-LLM. The MCP interface is for letting an agent consume evidence, not for outsourcing discovery to a model.

Can I install it from npm today?

The README lists npm installation as a future option. The verified current path is cloning the repository, running npm ci, and building locally.

Should `.portmap.json` be committed?

Only if the values are stable and safe to share. A committed static report can help future agents, but machine-specific listeners and environment details may be inappropriate for a repository.

Takeaway

The practical lesson is simple: make local topology an input to debugging. Build portmap from the documented source path, run declare before starting a long investigation, and let the report show which URLs are declared, which are actually reachable, and which assumptions are unsupported.

If you try this in a monorepo, which mismatch would be most valuable to catch first: stale environment URLs, Docker port remapping, or cross-workspace references?

AI assistance disclosure: AI assistance was used to organize and edit this tutorial. Repository behavior, commands, metadata, limitations, and verification claims were checked against the current public source and the clean checkout described above.

Build a Mobile Guitar Tuner with React, Express, and PostgreSQL

Fernando Paladini — Fri, 23 Oct 2026 12:35:12 +0000

If you want a guitar tuner that is easy to open on a phone or smartwatch, a small local web app can be more practical than a native installation. The hard part is not drawing six buttons. It is keeping the local setup reproducible while making the browser experience usable on a small screen.

This tutorial walks through the current main branch of Guitar Tune Trainer, an MIT-licensed open-source project owned by Fernando Paladini. You will install the project, start its PostgreSQL service, run the checks and production build, and understand what the repository currently does and does not provide.

TL;DR

The project is a React and Vite front end served by an Express application. Its documented local path is:

Install Node.js 18+, npm, and PostgreSQL support.
Clone the repository and run npm install.
Start PostgreSQL with the included Docker Compose file, or use another local database.
Copy .env.sample to .env and set a local SESSION_SECRET.
Run npm run db:push, then npm run dev.

The current repository also passes npm ci, npm run check, and npm run build on commit 26cfe55744aad30f2d30f03cdf70244bc0a91809.

Prerequisites

You need:

Node.js 18 or newer
npm
Docker Desktop with Compose, or a reachable PostgreSQL database
A modern browser if you want to use the mobile-oriented interface

The repository has no GitHub release or stable tag at the time of writing. Treat the commands below as instructions for the current main branch, not as a promise that a future release will have identical dependencies.

Start PostgreSQL locally

The repository includes a small docker-compose.yml that starts PostgreSQL 16 with a named volume:

docker compose up -d

The checked-in Compose configuration uses these local development values:

POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: guitar_tune_trainer

It publishes PostgreSQL on port 5432. These are development credentials from the repository configuration. Do not reuse them on a shared or internet-exposed database.

If port 5432 is already occupied, either stop the conflicting service or change the host-side port mapping. If you change the host port, update the connection string accordingly.

Install and configure the app

Clone the project and install the lockfile dependencies:

git clone https://github.com/paladini/guitar-tune-trainer.git
cd guitar-tune-trainer
npm ci

The current package.json identifies the package as version 1.0.0, uses ES modules, and declares the MIT license. Its scripts include dev, build, start, check, and db:push.

Create the local environment file from the checked-in example:

cp .env.sample .env

On Windows PowerShell, use this equivalent command:

Copy-Item .env.sample .env

The example contains:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/guitar_tune_trainer
SESSION_SECRET=your-session-secret
PORT=5000

Replace your-session-secret with a random value before using the app beyond a disposable local session. Keep .env out of version control. The repository's .gitignore is intended to support that local configuration pattern.

Apply the database schema and run the app

The repository's Drizzle configuration reads DATABASE_URL, and the documented schema currently defines a users table with a serial ID, unique username, and password field. Apply that schema with:

npm run db:push
npm run dev

The Express entry point defaults to port 5000, listens on 0.0.0.0, and serves the Vite development app after registering the server routes. Open http://localhost:5000 in a browser.

The HTML entry point is explicitly mobile-oriented. It sets a responsive viewport, describes the page as a smartwatch and mobile guitar tuner, links a web manifest, and includes Apple web-app metadata. The README describes the project as a PWA with offline support. Verify those capabilities in the browser you intend to use rather than assuming every browser exposes the same install prompt or audio behavior.

What the current code actually provides

The project is easiest to understand as two layers:

The client is a React application bundled with Vite and styled with Tailwind CSS and component primitives.
The server is an Express host with Drizzle-related database configuration and a memory-backed user storage implementation.

That distinction matters. The current server/routes.ts creates the HTTP server but does not register application API endpoints. The storage class keeps users in a process-local Map, while the shared schema describes PostgreSQL tables. The repository therefore demonstrates a runnable full-stack shell and a mobile tuner experience, but it is not yet a complete account-backed production service.

This is also why the first verification target should be the local page and build, not a claim that user data is persisted across restarts.

Reproducible verification

From a clean checkout, run the same checks used for this tutorial:

npm ci
npm run check
npm run build

npm ci installs the exact versions recorded in package-lock.json. npm run check runs TypeScript checking through tsc. npm run build runs the Vite client build and bundles the Express server with esbuild into dist.

On the current commit, all three commands completed successfully. The install also reported 35 audit findings in the dependency tree: 3 low, 11 moderate, 20 high, and 1 critical. That result is a reason to review and update dependencies before exposing the app publicly, not a reason to claim that the application is secure.

After the build, you can use the production-shaped command locally:

npm start

The application still requires the configured environment and database assumptions. Stop it with Ctrl+C when the smoke test is complete.

Failure modes and boundaries

PostgreSQL does not start

Check whether port 5432 is already in use and inspect the Compose logs:

docker compose ps
docker compose logs db

If you use a managed PostgreSQL provider instead, set DATABASE_URL to that provider's connection string and follow its TLS requirements.

The browser cannot access audio features

The repository presents reference-tone functionality as part of the tuner experience, but browser audio policies vary. Test on the target phone or watch, allow audio when prompted, and do not assume that a desktop result reproduces on a wearable browser.

Database changes appear not to persist

The schema and database configuration do not mean every feature is backed by PostgreSQL. The current route file has no registered application endpoints, and MemStorage stores users only in memory. Treat persistence as an unfinished boundary until the implementation changes and is verified.

Development credentials leak into deployment

The Compose file intentionally uses simple local credentials. Replace them, restrict network exposure, use a secret manager, and rotate any credential that may have been copied outside a disposable development environment.

FAQ

Can I run it without Docker?

Yes. The README lists local, Docker, or Neon PostgreSQL as options. Set DATABASE_URL to the database you control and run the same schema command.

Is there a stable release to pin?

No GitHub release or tag was present during this review. Pin a commit when reproducibility matters, and recheck the README and package metadata before upgrading.

Is this a production-ready authentication system?

No. The current repository contains a schema and in-memory storage skeleton, not a completed authentication flow. Do not put real credentials into it without implementing and reviewing authentication, password hashing, session handling, authorization, and database persistence.

Takeaway

Guitar Tune Trainer is a useful example of a small mobile-first full-stack web project: the command surface is compact, the browser entry point is designed for small screens, and the build is easy to verify locally. Its honest value today is the runnable interface and development scaffold. Its server-side persistence and security model still need deliberate engineering before deployment.

What would you build next: browser microphone pitch detection, a completed persisted account flow, or a smaller offline-only tuner with no server at all?

AI assistance disclosure

AI assistance was used to organize this tutorial and review the documented commands against the public repository. The repository behavior, configuration values, limitations, and validation results were checked against the cited primary sources and a clean local checkout.

DEV Community: Fernando Paladini

Build a Multilingual React Reflection Portal with GitHub Pages

TL;DR

Prerequisites

1. Get the project and inspect the data boundary

2. Install dependencies and build the portal

3. See how language selection becomes a file request

4. Load one language file and find one date

5. Verify the result without trusting the screen alone

6. Publish the static build

Why this pattern works

Limitations and security boundaries

FAQ

Do I need a backend?

Why keep JSON, CSV, and SQLite?

Can I add another language?

Takeaway

Choose an ActiveAdmin Theme with a Reviewable Rails Checklist

TL;DR

Prerequisites

1. Inspect the catalog as evidence

2. Keep the application change small

3. Verify the behavior in Rails

Why this workflow works

Failure modes and honest limits

The theme is listed but no longer works

The asset pipeline is different

The patch hides useful feedback

A private API changes

The repository contains old examples

FAQ

Does activeadmin-themes install a theme?

Is the flash-message initializer required?

Can I use a listed theme in production?

What should I contribute back?

Takeaway

AI assistance disclosure

Edit Currículo Lattes XML Safely with TypeScript and lattes-toolkit

TL;DR

Prerequisites

Install the pinned CLI

Inspect an exported curriculum

Make one narrow edit

Verify before import

Why this workflow is safer

Failure modes and limits

The field path is wrong

xmllint is unavailable

The platform rejects the import

Personal data leaks

FAQ

Does this package edit the online curriculum directly?

Can I use it with an AI agent?

Does validate prove the import will work?

Is this an official CNPq package?

Takeaway

Find Missing Loading and Error States in Next.js with unhappypath

TL;DR

Prerequisites

Build the scanner from source

Scan a project

Use the built-in fixtures to understand the output

Read findings as repair guidance

Add a conservative CI gate

Why this is useful, and where it stops

FAQ

Does it support every React framework?

Does a score of 100 mean the UI is production-ready?

Can I use it without installing the repository?

Takeaway

Add Local Developer Utilities to Any MCP Assistant with DevUtils

TL;DR

Prerequisites

Install and connect the server

Verify the transport before using tools

Use the tools for bounded operations

Why the MCP boundary helps

Important limitations and security boundaries

FAQ

Does the server need an API key?

`xmllint` is unavailable

Does `validate` prove the import will work?

Should I use the unpinned `npx devutils-mcp-server` command?