@forgerock/login-framework-cli 0.0.0-beta-20260713173318 → 0.0.0-beta-20260713183326

package/README.md

@@ -59,7 +59,7 @@ The `core/journey/_utilities/registry/custom-registry.ts` file is generated by t
 
 Scaffolds a new custom component under `experimental/custom/callbacks/<slug>/` or `experimental/custom/stages/<slug>/`. The Vite plugin watches these directories during `pnpm dev` and regenerates `custom-registry.ts` automatically on add/remove/change.
 
-Run from the root of an initialized project.
+Run from the root of an initialized project, or pass `--directory <path>` to target a specific project root.
 
 ```sh
 # Override the built-in NameCallback renderer
@@ -97,6 +97,64 @@ See `experimental/custom/README.md` for the full prop contract.
 
 ---
 
+### `ping-lf releases`
+
+Lists available framework releases from GitHub.
+
+```sh
+ping-lf releases
+```
+
+---
+
+### `ping-lf mcp`
+
+Boots the CLI as a local **MCP server** over stdio. Exposes the same commands as typed tools that any MCP-compatible AI assistant can call directly.
+
+#### Claude Code (project-local)
+
+Create `.claude/mcp.json` at the root of your login project:
+
+```jsonc
+{
+  "mcpServers": {
+    "ping-lf": {
+      "command": "npx",
+      "args": ["@forgerock/login-framework-cli", "mcp"]
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "ping-lf": {
+      "command": "npx",
+      "args": ["@forgerock/login-framework-cli", "mcp"]
+    }
+  }
+}
+```
+
+#### Available tools
+
+| Tool                | Description                          |
+| ------------------- | ------------------------------------ |
+| `init`              | Bootstrap a new project              |
+| `generate_callback` | Scaffold a custom callback component |
+| `generate_stage`    | Scaffold a custom stage component    |
+| `update`            | Update the framework version         |
+| `list_releases`     | List available releases from GitHub  |
+
+For `generate_callback`, `generate_stage`, and `update`, pass an absolute path via the `directory` parameter to target a specific project root. If omitted, the server's working directory is used.
+
+---
+
 ### `ping-lf update`
 
 Fetches the latest (or a specified) framework version and overwrites the core framework files while **preserving** `experimental/custom/` and project-level configs. The component registry is regenerated by the Vite plugin on the next build or dev-server start.
@@ -104,9 +162,10 @@ Fetches the latest (or a specified) framework version and overwrites the core fr
 Run from the root of an initialized project.
 
 ```sh
-ping-lf update                     # update to latest
-ping-lf update --tag v1.5.0        # pin to a specific release tag
-ping-lf update --local ../framework # use a local directory
+ping-lf update                          # update to latest
+ping-lf update --version v1.5.0         # pin to a specific version
+ping-lf update --local ../framework     # use a local directory
+ping-lf update --directory /path/to/project  # target a specific project root
 ```
 
 **What it preserves**
@@ -185,7 +244,8 @@ pnpm --filter @forgerock/login-framework-cli run dev       # tsc --watch
 ```
 tools/cli/
 ├── src/
-│   ├── main.ts                   # CLI entry point (ping-lf binary)
+│   ├── main.ts                   # Entry point — forks to MCP server or CLI
+│   ├── mcp.ts                    # MCP server (ping-lf --mcp)
 │   ├── errors.ts                 # Typed Effect errors
 │   ├── commands/
 │   │   ├── init.ts               # ping-lf init
@@ -208,5 +268,6 @@ tools/cli/
 
 - **[Effect](https://effect.website/)** — typed async handling, composable services, declarative errors
 - **[@effect/cli](https://github.com/Effect-TS/effect/tree/main/packages/cli)** — CLI parsing and help generation
+- **[@effect/ai](https://github.com/Effect-TS/effect/tree/main/packages/ai)** — MCP server (`McpServer`, `Tool`, `Toolkit`)
 - **[@effect/platform-node](https://github.com/Effect-TS/effect/tree/main/packages/platform-node)** — Node.js FileSystem, Path, HTTP client
 - **[Vitest](https://vitest.dev/)** — unit tests

package/dist/src/commands/generate.d.ts

@@ -1,6 +1,6 @@
 import { Command } from '@effect/cli';
 import { FileSystem, Path } from '@effect/platform';
-import { Schema } from 'effect';
+import { Effect, Schema } from 'effect';
 import { ComponentAlreadyExistsError, InvalidComponentNameError } from '../errors.js';
 /**
  * Validates a callback component name: must be a valid name (PascalCase, alphanumeric only).
@@ -19,7 +19,8 @@ export declare const StageNameSchema: Schema.transform<Schema.filter<typeof Sche
     name: typeof Schema.String;
     slug: typeof Schema.String;
 }>>;
-export declare const generateCommand: Command.Command<"generate", FileSystem.FileSystem | Path.Path | import("@effect/platform/Terminal").Terminal, import("../errors.js").GeneratorVersionError | InvalidComponentNameError | ComponentAlreadyExistsError | import("@effect/platform/Error").PlatformError | import("@effect/platform/Terminal").QuitException, {
+export declare function scaffoldComponent(type: 'callback' | 'stage', name: string, directory?: string): Effect.Effect<void, import("../errors.js").GeneratorVersionError | InvalidComponentNameError | ComponentAlreadyExistsError | import("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError, FileSystem.FileSystem | Path.Path>;
+export declare const generateCommand: Command.Command<"generate", FileSystem.FileSystem | Path.Path | import("@effect/platform/Terminal").Terminal, import("../errors.js").GeneratorVersionError | InvalidComponentNameError | ComponentAlreadyExistsError | import("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError | import("@effect/platform/Terminal").QuitException, {
     readonly subcommand: import("effect/Option").Option<{
         readonly name: string;
     } | {

package/dist/src/commands/generate.js

@@ -1,10 +1,13 @@
 import { Args, Command, Prompt } from '@effect/cli';
 import { FileSystem, Path } from '@effect/platform';
 import { Console, Effect, Schema } from 'effect';
+import { existsSync } from 'node:fs';
 import nodePath from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertValidProject } from '../config/version.js';
 import { ComponentAlreadyExistsError, InvalidComponentNameError } from '../errors.js';
+import { expandTilde } from '../services/file-system.js';
+import { runRegistryScript } from '../services/registry.js';
 import { toPascalCase } from '../utils.js';
 const CUSTOM_DIR = 'experimental/custom';
 /**
@@ -53,15 +56,17 @@ export const StageNameSchema = Schema.String.pipe(Schema.filter((s) => s.length
     encode: ({ name }) => name,
 }));
 /**
- * Resolves the templates directory relative to this compiled file.
- * Build script copies templates/ → dist/templates/, so from dist/commands/
- * the templates are one level up at dist/templates/.
+ * Resolves the templates directory relative to this file.
+ * In the compiled output (dist/src/commands/) the templates live one level up
+ * at dist/src/templates/. In Vitest (src/commands/) they live two levels up at
+ * the workspace root templates/ directory — the same fallback pattern used in mcp.ts.
  */
 function getTemplatesDir() {
     const __dirname = nodePath.dirname(fileURLToPath(import.meta.url));
-    return nodePath.join(__dirname, '../templates');
+    const compiledPath = nodePath.join(__dirname, '../templates');
+    return existsSync(compiledPath) ? compiledPath : nodePath.join(__dirname, '../../templates');
 }
-function scaffoldComponent(type, name) {
+export function scaffoldComponent(type, name, directory) {
     return Effect.gen(function* () {
         const fs = yield* FileSystem.FileSystem;
         const p = yield* Path.Path;
@@ -70,7 +75,7 @@ function scaffoldComponent(type, name) {
         // Stages are arbitrary AM strings with no naming convention constraint.
         const nameSchema = type === 'callback' ? CallbackNameSchema : StageNameSchema;
         const { slug } = yield* Schema.decode(nameSchema)(name).pipe(Effect.mapError(() => new InvalidComponentNameError({ name })));
-        const cwd = process.cwd();
+        const cwd = p.resolve(expandTilde(directory ?? process.cwd()));
         // ── Guard: must be run from an initialized project root ───────────────
         yield* assertValidProject(cwd);
         const subDir = type === 'callback' ? 'callbacks' : 'stages';
@@ -85,17 +90,14 @@ function scaffoldComponent(type, name) {
         // ── Create component directory ─────────────────────────────────────────
         yield* fs.makeDirectory(componentDir, { recursive: true });
         // ── Copy and process template files ───────────────────────────────────
-        // Each file name contains __COMPONENT_SLUG__; its contents use:
-        //   __COMPONENT_NAME__        — raw display name (may contain spaces, e.g. "My Login Stage")
-        //   __COMPONENT_NAME_PASCAL__ — PascalCase identifier derived from slug (e.g. "MyLoginStage"),
-        //                               safe for use in TypeScript symbol positions (function names etc.)
-        //   __COMPONENT_SLUG__        — kebab-case slug (e.g. "my-login-stage")
-        const pascalName = toPascalCase(name);
+        // Each file name contains __COMPONENT_SLUG__; its contents contain both
+        // __COMPONENT_NAME__ (PascalCase) and __COMPONENT_SLUG__ (kebab-case).
         const templateFiles = yield* fs.readDirectory(templatesDir);
         const createdFiles = [];
         for (const templateFile of templateFiles) {
             const targetFileName = templateFile.replaceAll('__COMPONENT_SLUG__', slug);
             const sourceContent = yield* fs.readFileString(p.join(templatesDir, templateFile));
+            const pascalName = toPascalCase(name);
             const processedContent = sourceContent
                 .replaceAll('__COMPONENT_NAME_PASCAL__', pascalName)
                 .replaceAll('__COMPONENT_NAME__', name)
@@ -104,12 +106,14 @@ function scaffoldComponent(type, name) {
             yield* fs.writeFileString(targetPath, processedContent);
             createdFiles.push(targetPath);
         }
+        // ── Regenerate custom-registry.ts ────────────────────────────────────
+        yield* Console.log('Regenerating custom component registry...');
+        yield* runRegistryScript(cwd);
         // ── Print summary ──────────────────────────────────────────────────────
         yield* Console.log(`Done. ${type} component scaffolded successfully.\n\n` +
             `Files created:\n` +
-            createdFiles.map((createdPath) => `  ${createdPath}`).join('\n') +
-            `\n\nNext: open ${p.join(componentDir, `${slug}.svelte`)} and implement your component.\n` +
-            `If a dev server is running, the registry will pick up the new component automatically.\n`);
+            createdFiles.map((f) => `  ${f}`).join('\n') +
+            `\n\nNext: open ${p.join(componentDir, `${slug}.svelte`)} and implement your component.\n`);
     });
 }
 // ── Subcommands ──────────────────────────────────────────────────────────────

package/dist/src/commands/init.d.ts

@@ -1,8 +1,16 @@
 import { Command } from '@effect/cli';
 import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
 import { DirectoryConflictError, DirectoryNotEmptyError } from '../errors.js';
-export declare const initCommand: Command.Command<"init", FileSystem.FileSystem | Path.Path | import("../services/release.js").Release, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError | import("../errors.js").FileSystemError | DirectoryConflictError | DirectoryNotEmptyError | import("@effect/platform/Error").PlatformError, {
+import type { Option } from 'effect';
+export interface InitProjectOptions {
     readonly directory: string;
-    readonly local: import("effect/Option").Option<string>;
-    readonly tag: import("effect/Option").Option<string>;
+    readonly local: Option.Option<string>;
+    readonly version: Option.Option<string>;
+}
+export declare const initProject: ({ directory, local, version }: InitProjectOptions) => Effect.Effect<void, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError | import("../errors.js").FileSystemError | DirectoryConflictError | DirectoryNotEmptyError | import("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError, FileSystem.FileSystem | Path.Path | import("../services/release.js").Release>;
+export declare const initCommand: Command.Command<"init", FileSystem.FileSystem | Path.Path | import("../services/release.js").Release, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError | import("../errors.js").FileSystemError | DirectoryConflictError | DirectoryNotEmptyError | import("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError, {
+    readonly directory: string;
+    readonly local: Option.Option<string>;
+    readonly version: Option.Option<string>;
 }>;

package/dist/src/commands/init.js

@@ -4,6 +4,7 @@ import { Console, Effect } from 'effect';
 import { writeVersion } from '../config/version.js';
 import { DirectoryConflictError, DirectoryNotEmptyError } from '../errors.js';
 import { copyWithExclusions, expandTilde, isFrameworkDirectory } from '../services/file-system.js';
+import { runRegistryScript } from '../services/registry.js';
 import { resolveSource } from './source.js';
 /**
  * Minimal pnpm-workspace.yaml written to the customer project.
@@ -28,11 +29,7 @@ To scaffold your first custom component:
 
 Read the authoring guide: experimental/custom/README.md
 `;
-export const initCommand = Command.make('init', {
-    directory: Args.text({ name: 'directory' }).pipe(Args.withDescription('Directory to initialize the project in. Use "./" for the current directory.')),
-    local: Options.optional(Options.text('local').pipe(Options.withDescription('Path to a local framework directory. If omitted, the main branch is downloaded from GitHub.'))),
-    tag: Options.optional(Options.text('tag').pipe(Options.withDescription('Framework release tag to download (e.g. v1.2.0). If omitted, the main branch is used.'))),
-}, ({ directory, local, tag }) => Effect.gen(function* () {
+export const initProject = ({ directory, local, version }) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const resolvedDir = path.resolve(expandTilde(directory));
@@ -55,7 +52,7 @@ export const initCommand = Command.make('init', {
     // Effect.scoped closes the Scope that release.fetch opens, triggering
     // automatic removal of the .framework-tmp directory after copying.
     const resolvedVersion = yield* Effect.scoped(Effect.gen(function* () {
-        const { sourceDir, resolvedVersion } = yield* resolveSource(local, tag, resolvedDir);
+        const { sourceDir, resolvedVersion } = yield* resolveSource(local, version, resolvedDir);
         // ── 2. Create target directory + copy framework (with exclusions) ──
         yield* Console.log('Copying framework files...');
         yield* fs.makeDirectory(resolvedDir, { recursive: true });
@@ -75,11 +72,22 @@ export const initCommand = Command.make('init', {
         yield* fs.makeDirectory(customDir, { recursive: true });
         yield* fs.writeFileString(path.join(customDir, '.gitkeep'), '');
     }), { concurrency: 'unbounded', discard: true });
-    // ── 5. Write .generator-version ────────────────────────────────────────
+    // ── 5. Generate custom-registry.ts ────────────────────────────────────
+    // Run the canonical registry script so the file is immediately present
+    // with the correct CustomRegistryEntry format. The empty callbacks/ and
+    // stages/ dirs produce empty registries — no custom components yet.
+    yield* Console.log('Generating custom component registry...');
+    yield* runRegistryScript(resolvedDir);
+    // ── 6. Write .generator-version ────────────────────────────────────────
     yield* writeVersion(resolvedDir, {
         version: resolvedVersion,
         generatedAt: new Date().toISOString(),
     });
-    // ── 6. Print next steps ───────────────────────────────────────────────
+    // ── 7. Print next steps ───────────────────────────────────────────────
     yield* Console.log(nextStepsMessage(directory));
-})).pipe(Command.withDescription('Bootstrap a new Ping Login Widget or Login App project from a GitHub release or a local framework path.'));
+});
+export const initCommand = Command.make('init', {
+    directory: Args.text({ name: 'directory' }).pipe(Args.withDescription('Directory to initialize the project in. Use "./" for the current directory.')),
+    local: Options.optional(Options.text('local').pipe(Options.withDescription('Path to a local framework directory. If omitted, the main branch is downloaded from GitHub.'))),
+    version: Options.optional(Options.text('version').pipe(Options.withDescription('Framework release tag to download (e.g. v1.2.0). If omitted, the main branch is used.'))),
+}, ({ directory, local, version }) => initProject({ directory, local, version })).pipe(Command.withDescription('Bootstrap a new Ping Login Widget or Login App project from a GitHub release or a local framework path.'));

package/dist/src/commands/update.d.ts

@@ -1,5 +1,7 @@
 import { Command } from '@effect/cli';
-export declare const updateCommand: Command.Command<"update", import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path | import("../services/release.js").Release, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError | import("../errors.js").FileSystemError | import("../errors.js").GeneratorVersionError | import("@effect/platform/Error").PlatformError, {
-    readonly local: import("effect/Option").Option<string>;
-    readonly tag: import("effect/Option").Option<string>;
+import { Option } from 'effect';
+export declare const updateCommand: Command.Command<"update", import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path | import("../services/release.js").Release, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError | import("../errors.js").FileSystemError | import("../errors.js").GeneratorVersionError | import("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError, {
+    readonly directory: Option.Option<string>;
+    readonly local: Option.Option<string>;
+    readonly version: Option.Option<string>;
 }>;

package/dist/src/commands/update.js

@@ -1,13 +1,16 @@
 import { Command, Options } from '@effect/cli';
-import { Console, Effect } from 'effect';
+import { Console, Effect, Option } from 'effect';
+import nodePath from 'node:path';
 import { assertValidProject, writeVersion } from '../config/version.js';
-import { copyWithExclusions } from '../services/file-system.js';
+import { copyWithExclusions, expandTilde } from '../services/file-system.js';
+import { runRegistryScript } from '../services/registry.js';
 import { resolveSource } from './source.js';
 export const updateCommand = Command.make('update', {
+    directory: Options.optional(Options.text('directory').pipe(Options.withDescription('Project root directory. Defaults to the current working directory.'))),
     local: Options.optional(Options.text('local').pipe(Options.withDescription('Path to a local framework directory. If omitted, the main branch is downloaded from GitHub.'))),
-    tag: Options.optional(Options.text('tag').pipe(Options.withDescription('Framework release tag to update to (e.g. v1.2.0). If omitted, the main branch is used.'))),
-}, ({ local, tag }) => Effect.gen(function* () {
-    const cwd = process.cwd();
+    version: Options.optional(Options.text('version').pipe(Options.withDescription('Framework version tag to update to (e.g. v1.2.0). If omitted, the main branch is used.'))),
+}, ({ local, version, directory }) => Effect.gen(function* () {
+    const cwd = nodePath.resolve(expandTilde(Option.getOrElse(directory, () => process.cwd())));
     // ── 1. Verify this is an initialized project ──────────────────────────
     const currentVersion = yield* assertValidProject(cwd);
     yield* Console.log(`\nUpdating project from version: ${currentVersion.version}\n`);
@@ -15,16 +18,20 @@ export const updateCommand = Command.make('update', {
     // Effect.scoped closes the Scope that release.fetch opens, triggering
     // automatic removal of the .framework-tmp directory after copying.
     const resolvedVersion = yield* Effect.scoped(Effect.gen(function* () {
-        const { sourceDir, resolvedVersion } = yield* resolveSource(local, tag, cwd);
+        const { sourceDir, resolvedVersion } = yield* resolveSource(local, version, cwd);
         yield* Console.log('Copying updated framework files...');
         yield* copyWithExclusions(sourceDir, cwd);
         return resolvedVersion;
     }));
-    // ── 3. Update .generator-version ──────────────────────────────────────
+    // ── 3. Regenerate custom-registry.ts ──────────────────────────────────
+    yield* Console.log('Regenerating custom component registry...');
+    yield* runRegistryScript(cwd);
+    // ── 4. Update .generator-version ──────────────────────────────────────
     yield* writeVersion(cwd, {
         version: resolvedVersion,
         generatedAt: new Date().toISOString(),
     });
     yield* Console.log(`\nDone. Updated from ${currentVersion.version} to ${resolvedVersion}.\n` +
+        'Custom component registry regenerated.\n' +
         'Run "pnpm install" if package dependencies changed.\n');
 })).pipe(Command.withDescription('Fetch the latest (or a specified) framework version and overwrite core files while preserving experimental/custom/.'));

package/dist/src/errors.d.ts

@@ -79,4 +79,12 @@ export declare class ComponentAlreadyExistsError extends ComponentAlreadyExistsE
     readonly path: string;
 }> {
 }
+declare const RegistryScanError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RegistryScanError";
+} & Readonly<A>;
+export declare class RegistryScanError extends RegistryScanError_base<{
+    readonly directory: string;
+    readonly cause?: unknown;
+}> {
+}
 export {};

package/dist/src/errors.js

@@ -21,3 +21,5 @@ export class InvalidComponentNameError extends Data.TaggedError('InvalidComponen
 }
 export class ComponentAlreadyExistsError extends Data.TaggedError('ComponentAlreadyExistsError') {
 }
+export class RegistryScanError extends Data.TaggedError('RegistryScanError') {
+}

package/dist/src/main.js

@@ -1,34 +1,61 @@
 #!/usr/bin/env node
 import { Command } from '@effect/cli';
 import { NodeContext, NodeRuntime } from '@effect/platform-node';
-import { Console, Effect } from 'effect';
-import { createRequire } from 'node:module';
+import { Console, Effect, Layer } from 'effect';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { generateCommand } from './commands/generate.js';
 import { initCommand } from './commands/init.js';
 import { releasesCommand } from './commands/releases.js';
 import { updateCommand } from './commands/update.js';
+import { mcpCommand, ServerLayer } from './mcp.js';
 import { GithubReleaseLayer } from './services/release.js';
-// Read the version from package.json at runtime so it stays in sync
-// with the published package version after changesets bumps it.
-const { version } = createRequire(import.meta.url)('../../package.json');
-const rootCommand = Command.make('ping-lf').pipe(Command.withDescription('CLI for initializing, scaffolding, and updating Ping Login Widget and Login App custom component projects.'), Command.withSubcommands([initCommand, generateCommand, updateCommand, releasesCommand]));
+function readCliVersion() {
+    try {
+        const raw = readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.version)
+            throw new Error('Missing "version" field in package.json');
+        return parsed.version;
+    }
+    catch (err) {
+        process.stderr.write(`Failed to read CLI version: ${String(err)}\n`);
+        process.exit(1);
+    }
+}
+const version = readCliVersion();
+const rootCommand = Command.make('ping-lf').pipe(Command.withDescription('CLI for initializing, scaffolding, and updating Ping Login Widget and Login App custom component projects.'), Command.withSubcommands([
+    initCommand,
+    generateCommand,
+    updateCommand,
+    releasesCommand,
+    mcpCommand,
+]));
 const cli = Command.run(rootCommand, {
     name: 'ping-lf',
     version,
 });
-cli(process.argv).pipe(Effect.catchTag('DirectoryConflictError', (err) => Console.error(`\nError: "${err.path}" already contains a framework project.` +
-    `\n  Did you mean to use --local?\n` +
-    `\n    ping-lf init <new-directory> --local ${err.path}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('DirectoryNotEmptyError', (err) => Console.error(`\nError: "${err.path}" already exists and is not empty.` +
-    `\n  Choose a different directory name, or delete the existing directory first.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseNetworkError', (err) => Console.error(`\nError: Could not reach GitHub to download the release.\n` +
-    `  ${err.cause}\n\n` +
-    `  • Check your network connection and try again.\n` +
-    `  • Use a local path:   ping-lf init <dir> --local <path>\n` +
-    `  • Specify a tag:      ping-lf init <dir> --tag v1.0.0\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseParseError', (err) => Console.error(`\nError: Failed to parse the release data.\n  ${err.cause}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseFsError', (err) => Console.error(`\nError: Filesystem error during release download (${err.operation}).\n  ${err.cause}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('InvalidVersionError', (err) => Console.error(`\nError: "${err.version}" is not a valid version tag.\n` +
-    `  Expected semver format like v1.0.0.\n` +
-    `  Use "ping-lf releases" to list available versions.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseNotFoundError', (err) => Console.error(`\nError: No releases found on GitHub.` +
-    (err.cause ? `\n  ${err.cause}` : '') +
-    `\n\n  • Check your network connection and try again.\n` +
-    `  • Use a local path:   ping-lf init <dir> --local <path>\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('InvalidComponentNameError', (err) => Console.error(`\nError: "${err.name}" is not a valid component name.\n` +
-    `  Names must be PascalCase, start with an uppercase letter, and contain only letters and digits.\n` +
-    `  Examples: MyCallback, JWTLogin, DefaultStage\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ComponentAlreadyExistsError', (err) => Console.error(`\nError: component directory already exists: ${err.path}\n` +
-    `  Choose a different name or delete the existing directory first.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.provide(GithubReleaseLayer), Effect.provide(NodeContext.layer), (effect) => NodeRuntime.runMain(effect, { disableErrorReporting: true }));
+// Detect `ping-lf mcp` early so we can launch the MCP server via Layer.launch,
+// which cannot be composed with the @effect/cli Effect pipeline. When --help or
+// -h is present we fall through to the CLI so the user still gets usage output.
+const isMcpLaunch = process.argv[2] === 'mcp' && !process.argv.includes('--help') && !process.argv.includes('-h');
+const program = isMcpLaunch
+    ? Layer.launch(ServerLayer)
+    : cli(process.argv).pipe(Effect.catchTag('DirectoryConflictError', (err) => Console.error(`\nError: "${err.path}" already contains a framework project.` +
+        `\n  Did you mean to use --local?\n` +
+        `\n    ping-lf init <new-directory> --local ${err.path}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('DirectoryNotEmptyError', (err) => Console.error(`\nError: "${err.path}" already exists and is not empty.` +
+        `\n  Choose a different directory name, or delete the existing directory first.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseNetworkError', (err) => Console.error(`\nError: Could not reach GitHub to download the release.\n` +
+        `  ${err.cause}\n\n` +
+        `  • Check your network connection and try again.\n` +
+        `  • Use a local path:   ping-lf init <dir> --local <path>\n` +
+        `  • Specify a version:  ping-lf init <dir> --version v1.0.0\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseParseError', (err) => Console.error(`\nError: Failed to parse the release data.\n  ${err.cause}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseFsError', (err) => Console.error(`\nError: Filesystem error during release download (${err.operation}).\n  ${err.cause}\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('InvalidVersionError', (err) => Console.error(`\nError: "${err.version}" is not a valid version tag.\n` +
+        `  Expected semver format like v1.0.0.\n` +
+        `  Use "ping-lf releases" to list available versions.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ReleaseNotFoundError', (err) => Console.error(`\nError: No releases found on GitHub.` +
+        (err.cause ? `\n  ${err.cause}` : '') +
+        `\n\n  • Check your network connection and try again.\n` +
+        `  • Use a local path:   ping-lf init <dir> --local <path>\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('InvalidComponentNameError', (err) => Console.error(`\nError: "${err.name}" is not a valid component name.\n` +
+        `  Names must be PascalCase, start with an uppercase letter, and contain only letters and digits.\n` +
+        `  Examples: MyCallback, JWTLogin, DefaultStage\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.catchTag('ComponentAlreadyExistsError', (err) => Console.error(`\nError: component directory already exists: ${err.path}\n` +
+        `  Choose a different name or delete the existing directory first.\n`).pipe(Effect.andThen(Effect.die(err)))), Effect.provide(Layer.mergeAll(GithubReleaseLayer, NodeContext.layer)));
+NodeRuntime.runMain(program, { disableErrorReporting: true });

package/dist/src/mcp.d.ts

@@ -0,0 +1,52 @@
+import { Tool, Toolkit } from '@effect/ai';
+import { Command } from '@effect/cli';
+import { Layer, Schema } from 'effect';
+export declare const mcpToolkit: Toolkit.Toolkit<{
+    readonly init: Tool.Tool<"init", {
+        readonly parameters: Schema.Struct<{
+            directory: Schema.SchemaClass<string, string, never>;
+            version: Schema.optional<typeof Schema.String>;
+            local: Schema.optional<typeof Schema.String>;
+        }>;
+        readonly success: typeof Schema.String;
+        readonly failure: typeof Schema.String;
+        readonly failureMode: "error";
+    }, never>;
+    readonly generate_callback: Tool.Tool<"generate_callback", {
+        readonly parameters: Schema.Struct<{
+            name: Schema.SchemaClass<string, string, never>;
+            directory: Schema.optional<typeof Schema.String>;
+        }>;
+        readonly success: typeof Schema.String;
+        readonly failure: typeof Schema.String;
+        readonly failureMode: "error";
+    }, never>;
+    readonly generate_stage: Tool.Tool<"generate_stage", {
+        readonly parameters: Schema.Struct<{
+            name: Schema.SchemaClass<string, string, never>;
+            directory: Schema.optional<typeof Schema.String>;
+        }>;
+        readonly success: typeof Schema.String;
+        readonly failure: typeof Schema.String;
+        readonly failureMode: "error";
+    }, never>;
+    readonly update: Tool.Tool<"update", {
+        readonly parameters: Schema.Struct<{
+            directory: Schema.optional<typeof Schema.String>;
+            version: Schema.optional<typeof Schema.String>;
+            local: Schema.optional<typeof Schema.String>;
+        }>;
+        readonly success: typeof Schema.String;
+        readonly failure: typeof Schema.String;
+        readonly failureMode: "error";
+    }, never>;
+    readonly list_releases: Tool.Tool<"list_releases", {
+        readonly parameters: Schema.Struct<{}>;
+        readonly success: typeof Schema.String;
+        readonly failure: typeof Schema.String;
+        readonly failureMode: "error";
+    }, never>;
+}>;
+declare const ServerLayer: Layer.Layer<never, never, never>;
+export { ServerLayer };
+export declare const mcpCommand: Command.Command<"mcp", never, never, {}>;

package/dist/src/mcp.js

@@ -0,0 +1,182 @@
+import { McpServer, Tool, Toolkit } from '@effect/ai';
+import { Command } from '@effect/cli';
+import { NodeContext, NodeSink, NodeStream } from '@effect/platform-node';
+import { Cause, Effect, Layer, Logger, Option, Schema } from 'effect';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scaffoldComponent } from './commands/generate.js';
+import { initProject } from './commands/init.js';
+import { resolveSource } from './commands/source.js';
+import { assertValidProject, writeVersion } from './config/version.js';
+import { copyWithExclusions, expandTilde } from './services/file-system.js';
+import { runRegistryScript } from './services/registry.js';
+import { GithubReleaseLayer, Release } from './services/release.js';
+// Resolve package.json from either dist/src/ (compiled) or src/ (Vitest).
+const __dir = dirname(fileURLToPath(import.meta.url));
+const pkgPath = existsSync(resolve(__dir, '../../package.json'))
+    ? resolve(__dir, '../../package.json')
+    : resolve(__dir, '../package.json');
+const { version } = JSON.parse(readFileSync(pkgPath, 'utf8'));
+// ── Shared error formatter ────────────────────────────────────────────────────
+function formatError(cause) {
+    const err = Cause.failureOption(cause);
+    if (Option.isSome(err)) {
+        const e = err.value;
+        switch (e._tag) {
+            case 'InvalidVersionError':
+                return `Invalid version "${e['version']}". Expected semver format like v1.0.0.`;
+            case 'ReleaseNetworkError':
+                return `Network error reaching GitHub: ${e['cause']}`;
+            case 'ReleaseParseError':
+                return `Failed to parse release data: ${e['cause']}`;
+            case 'ReleaseFsError':
+                return `Filesystem error during ${e['operation']}: ${e['cause']}`;
+            case 'ReleaseNotFoundError':
+                return `No releases found on GitHub${e['cause'] ? `: ${e['cause']}` : ''}.`;
+            case 'FileSystemError':
+                return `Filesystem error (${e['operation']}) at "${e['path']}": ${e['cause']}`;
+            case 'GeneratorVersionError':
+                return `Generator version error: ${e['message']}${e['path'] ? ` (${e['path']})` : ''}`;
+            case 'RegistryScanError':
+                return `Registry scan failed in "${e['directory']}": ${e['cause']}`;
+            case 'DirectoryConflictError':
+                return `"${e['path']}" already contains a framework project. Use local path instead.`;
+            case 'DirectoryNotEmptyError':
+                return `"${e['path']}" already exists and is not empty.`;
+            case 'InvalidComponentNameError':
+                return `"${e['name']}" is not a valid component name. Use PascalCase (e.g. MyCallback).`;
+            case 'ComponentAlreadyExistsError':
+                return `Component directory already exists: ${e['path']}`;
+            default:
+                try {
+                    return `Error: ${JSON.stringify(e, (_k, v) => v instanceof Error ? { message: v.message, name: v.name } : v)}`;
+                }
+                catch {
+                    return `Error: ${String(e)}`;
+                }
+        }
+    }
+    return `Unexpected error: ${Cause.pretty(cause)}`;
+}
+const toolLayer = Layer.mergeAll(GithubReleaseLayer, NodeContext.layer);
+const catchToolErrors = (effect) => effect.pipe(Effect.provide(toolLayer), Effect.catchAll((err) => Effect.fail(formatError(Cause.fail(err)))));
+// ── Tool definitions ─────────────────────────────────────────────────────────
+const InitTool = Tool.make('init', {
+    description: 'Bootstrap a new Ping Login Widget / Login App project from a GitHub release or local path.',
+    parameters: {
+        directory: Schema.String.annotations({
+            description: 'Directory to initialize the project in (e.g. "my-project" or "./")',
+        }),
+        version: Schema.optional(Schema.String).annotations({
+            description: 'Framework version tag to download (e.g. v1.2.0). Defaults to latest.',
+        }),
+        local: Schema.optional(Schema.String).annotations({
+            description: 'Path to a local framework directory instead of downloading from GitHub.',
+        }),
+    },
+    success: Schema.String,
+    failure: Schema.String,
+})
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, true)
+    .annotate(Tool.Idempotent, false);
+const directoryParam = Schema.optional(Schema.String).annotations({
+    description: 'Absolute path to the initialized project root. Defaults to the current working directory.',
+});
+const GenerateCallbackTool = Tool.make('generate_callback', {
+    description: 'Scaffold a new custom callback component under experimental/custom/callbacks/. Run from an initialized project root.',
+    parameters: {
+        name: Schema.String.annotations({
+            description: 'PascalCase component name (e.g. MyCallback). Must match the AM callback type string.',
+        }),
+        directory: directoryParam,
+    },
+    success: Schema.String,
+    failure: Schema.String,
+})
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, false)
+    .annotate(Tool.Idempotent, false);
+const GenerateStageTool = Tool.make('generate_stage', {
+    description: 'Scaffold a new custom stage component under experimental/custom/stages/. Run from an initialized project root.',
+    parameters: {
+        name: Schema.String.annotations({
+            description: 'Stage name as configured on the AM journey Page Node (e.g. "DefaultLogin" or "My Login Stage").',
+        }),
+        directory: directoryParam,
+    },
+    success: Schema.String,
+    failure: Schema.String,
+})
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, false)
+    .annotate(Tool.Idempotent, false);
+const UpdateTool = Tool.make('update', {
+    description: 'Fetch the latest (or specified) framework version and overwrite core files while preserving experimental/custom/. Run from an initialized project root.',
+    parameters: {
+        directory: directoryParam,
+        version: Schema.optional(Schema.String).annotations({
+            description: 'Framework version tag to update to (e.g. v1.2.0). Defaults to latest.',
+        }),
+        local: Schema.optional(Schema.String).annotations({
+            description: 'Path to a local framework directory instead of downloading from GitHub.',
+        }),
+    },
+    success: Schema.String,
+    failure: Schema.String,
+})
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, true)
+    .annotate(Tool.Idempotent, false);
+const ListReleasesTool = Tool.make('list_releases', {
+    description: 'List available Login Framework releases from GitHub.',
+    parameters: {},
+    success: Schema.String,
+    failure: Schema.String,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true)
+    .annotate(Tool.Idempotent, true);
+// ── Exported toolkit (used in tests) ─────────────────────────────────────────
+export const mcpToolkit = Toolkit.make(InitTool, GenerateCallbackTool, GenerateStageTool, UpdateTool, ListReleasesTool);
+// ── Tool handlers ─────────────────────────────────────────────────────────────
+const handlerLayer = mcpToolkit.toLayer({
+    init: ({ directory, version: ver, local }) => catchToolErrors(initProject({
+        directory,
+        version: Option.fromNullable(ver),
+        local: Option.fromNullable(local),
+    }).pipe(Effect.map(() => `Project initialized successfully in "${directory}".`))),
+    generate_callback: ({ name, directory }) => catchToolErrors(scaffoldComponent('callback', name, directory).pipe(Effect.map(() => `Callback component "${name}" scaffolded successfully.`))),
+    generate_stage: ({ name, directory }) => catchToolErrors(scaffoldComponent('stage', name, directory).pipe(Effect.map(() => `Stage component "${name}" scaffolded successfully.`))),
+    update: ({ version: ver, local, directory }) => catchToolErrors(Effect.gen(function* () {
+        const cwd = resolve(expandTilde(directory ?? process.cwd()));
+        const currentVersion = yield* assertValidProject(cwd);
+        const resolvedVersion = yield* Effect.scoped(Effect.gen(function* () {
+            const { sourceDir, resolvedVersion } = yield* resolveSource(Option.fromNullable(local), Option.fromNullable(ver), cwd);
+            yield* copyWithExclusions(sourceDir, cwd);
+            return resolvedVersion;
+        }));
+        yield* runRegistryScript(cwd);
+        yield* writeVersion(cwd, {
+            version: resolvedVersion,
+            generatedAt: new Date().toISOString(),
+        });
+        return `Updated from ${currentVersion.version} to ${resolvedVersion}. Run "pnpm install" if dependencies changed.`;
+    })),
+    list_releases: () => catchToolErrors(Release.pipe(Effect.flatMap((release) => release.listReleases()), Effect.map((releases) => releases.map(({ tag, publishedAt }) => `${tag.padEnd(10)} ${publishedAt}`).join('\n')))),
+});
+// ── Server layer ──────────────────────────────────────────────────────────────
+const ServerLayer = McpServer.toolkit(mcpToolkit).pipe(Layer.provide(handlerLayer), Layer.provide(Layer.mergeAll(McpServer.layerStdio({
+    name: 'ping-lf',
+    version,
+    stdin: NodeStream.stdin,
+    stdout: NodeSink.stdout,
+}), NodeContext.layer, Logger.add(Logger.prettyLogger({ stderr: true })))));
+export { ServerLayer };
+// mcpCommand is registered only so `ping-lf --help` lists `mcp` as a subcommand.
+// The actual MCP dispatch happens in main.ts via Layer.launch(ServerLayer) at the
+// top level, outside the @effect/cli command handler where Layer.launch would
+// nest a second fiber scope inside the CLI's already-running one.
+export const mcpCommand = Command.make('mcp', {}, () => Effect.void).pipe(Command.withDescription('Start as an MCP server over stdio.'));

package/dist/src/services/registry.d.ts

@@ -0,0 +1,22 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { RegistryScanError } from '../errors.js';
+type ComponentType = 'stage' | 'callback';
+/** Extracts names of all `export let` prop declarations from a Svelte component's `<script>` block. */
+export declare function parseAcceptedProps(content: string): string[];
+/** Parses and validates the leading `<!-- @component -->` block from a Svelte file. */
+export declare const parseComponentHeader: (filePath: string, content: string) => Effect.Effect<{
+    type: ComponentType;
+    name: string;
+}, RegistryScanError>;
+/**
+ * Scans `experimental/custom/stages/` and `experimental/custom/callbacks/` for
+ * `@component`-annotated Svelte files and writes
+ * `core/journey/_utilities/custom-registry.ts`.
+ *
+ * All I/O runs in-process via the platform `FileSystem` service — no subprocess
+ * spawning. Validation errors across multiple components are collected and
+ * reported together.
+ */
+export declare const runRegistryScript: (projectDir: string) => Effect.Effect<void, RegistryScanError, FileSystem.FileSystem | Path.Path>;
+export {};

package/dist/src/services/registry.js

@@ -0,0 +1,169 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Console, Effect } from 'effect';
+import { RegistryScanError } from '../errors.js';
+// --------------------------------------------------------------------------
+// Helpers (exported for testing)
+// --------------------------------------------------------------------------
+/** Extracts names of all `export let` prop declarations from a Svelte component's `<script>` block. */
+export function parseAcceptedProps(content) {
+    const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/);
+    if (!scriptMatch)
+        return [];
+    const props = [];
+    const regex = /export\s+let\s+(\w+)/g;
+    let m;
+    while ((m = regex.exec(scriptMatch[1])) !== null)
+        props.push(m[1]);
+    return props;
+}
+function toPascalCase(str) {
+    return str
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
+        .replace(/^(.)/, (_, chr) => chr.toUpperCase());
+}
+/** Parses and validates the leading `<!-- @component -->` block from a Svelte file. */
+export const parseComponentHeader = (filePath, content) => {
+    const fail = (cause) => Effect.fail(new RegistryScanError({ directory: filePath, cause }));
+    const commentMatch = content.match(/^<!--([\s\S]*?)-->/);
+    if (!commentMatch)
+        return fail('Missing @component header. Every custom component must begin with:\n' +
+            '<!--\n   @component\n   Type: stage|callback\n   Name: <ComponentName>\n   -->');
+    const block = commentMatch[1];
+    if (!block.includes('@component'))
+        return fail('Missing "@component" tag in the opening comment.');
+    const typeMatch = block.match(/Type:\s*(\S+)/);
+    if (!typeMatch)
+        return fail('Missing "Type:" field in @component header. Expected: Type: stage or Type: callback');
+    const rawType = typeMatch[1].toLowerCase();
+    if (rawType !== 'stage' && rawType !== 'callback')
+        return fail(`Invalid Type value "${typeMatch[1]}". Must be "stage" or "callback".`);
+    const nameMatch = block.match(/Name:\s*(.+)/);
+    if (!nameMatch)
+        return fail('Missing "Name:" field in @component header. Expected: Name: <ComponentName>');
+    return Effect.succeed({ type: rawType, name: nameMatch[1].trim() });
+};
+// --------------------------------------------------------------------------
+// File scanning
+// --------------------------------------------------------------------------
+const findSvelteFiles = (fs, path, dir) => fs.exists(dir).pipe(Effect.orElseSucceed(() => false), Effect.flatMap((exists) => !exists
+    ? Effect.succeed([])
+    : fs.readDirectory(dir).pipe(Effect.mapError((cause) => new RegistryScanError({ directory: dir, cause })), Effect.flatMap((entries) => Effect.forEach(entries, (entry) => {
+        const fullPath = path.join(dir, entry);
+        return fs.stat(fullPath).pipe(Effect.mapError((cause) => new RegistryScanError({ directory: dir, cause })), Effect.flatMap((stat) => stat.type === 'Directory'
+            ? findSvelteFiles(fs, path, fullPath)
+            : Effect.succeed(entry.endsWith('.svelte') && !entry.endsWith('.story.svelte')
+                ? [fullPath]
+                : [])));
+    }, { concurrency: 'unbounded' })), Effect.map((nested) => nested.flat()))));
+const scanDirectory = (fs, path, dir, expectedType) => findSvelteFiles(fs, path, dir).pipe(Effect.flatMap((files) => Effect.validateAll(files, (filePath) => fs.readFileString(filePath).pipe(Effect.mapError((cause) => new RegistryScanError({ directory: filePath, cause })), Effect.flatMap((content) => parseComponentHeader(filePath, content).pipe(Effect.flatMap(({ type, name }) => type !== expectedType
+    ? Effect.fail(new RegistryScanError({
+        directory: filePath,
+        cause: `Component in /experimental/custom/${expectedType}s/ declares Type: "${type}". Must declare Type: ${expectedType}`,
+    }))
+    : Effect.succeed({
+        filePath,
+        name,
+        type,
+        acceptedProps: parseAcceptedProps(content),
+    })))))).pipe(Effect.mapError((errors) => new RegistryScanError({
+    directory: dir,
+    cause: errors.map((e) => String(e.cause)).join('\n'),
+})))));
+// --------------------------------------------------------------------------
+// Registry content builder (pure)
+// --------------------------------------------------------------------------
+function buildRegistryContent(path, registryDir, stageComponents, callbackComponents) {
+    const toEntry = (prefix) => ({ filePath, name, acceptedProps }) => {
+        const relPath = path.relative(registryDir, filePath).replace(/\\/g, '/');
+        const importPath = relPath.startsWith('.') ? relPath : `./${relPath}`;
+        return { varName: `${prefix}${toPascalCase(name)}`, importPath, name, acceptedProps };
+    };
+    const stageEntries = stageComponents.map(toEntry('Stage'));
+    const callbackEntries = callbackComponents.map(toEntry('Callback'));
+    const lines = [
+        `/**`,
+        ` * AUTO-GENERATED — do not edit by hand.`,
+        ` * Run \`pnpm build:widget\` or \`pnpm --filter @forgerock/login-widget exec vite build\` to regenerate.`,
+        ` *`,
+        ` * Source: /experimental/custom/stages/ and /experimental/custom/callbacks/`,
+        ` */`,
+        ``,
+        `import type { Component } from 'svelte';`,
+        ``,
+        `export interface CustomRegistryEntry {`,
+        `  component: Component;`,
+        `  /** Props declared via \`export let\` in the component — only these are forwarded by the mapper. */`,
+        `  acceptedProps: string[];`,
+        `}`,
+        ``,
+    ];
+    if (stageEntries.length > 0) {
+        lines.push(`// Stage overrides / extensions`);
+        for (const { varName, importPath } of stageEntries)
+            lines.push(`import ${varName} from '${importPath}';`);
+        lines.push(``);
+    }
+    if (callbackEntries.length > 0) {
+        lines.push(`// Callback overrides / extensions`);
+        for (const { varName, importPath } of callbackEntries)
+            lines.push(`import ${varName} from '${importPath}';`);
+        lines.push(``);
+    }
+    lines.push(`export const customStageRegistry: Record<string, CustomRegistryEntry> = {`);
+    for (const { varName, name, acceptedProps } of stageEntries)
+        lines.push(`  ${JSON.stringify(name)}: { component: ${varName}, acceptedProps: ${JSON.stringify(acceptedProps)} },`);
+    lines.push(`};`);
+    lines.push(``);
+    lines.push(`export const customCallbackRegistry: Record<string, CustomRegistryEntry> = {`);
+    for (const { varName, name, acceptedProps } of callbackEntries)
+        lines.push(`  ${JSON.stringify(name)}: { component: ${varName}, acceptedProps: ${JSON.stringify(acceptedProps)} },`);
+    lines.push(`};`);
+    lines.push(``);
+    return lines.join('\n');
+}
+// --------------------------------------------------------------------------
+// Public API
+// --------------------------------------------------------------------------
+/**
+ * Scans `experimental/custom/stages/` and `experimental/custom/callbacks/` for
+ * `@component`-annotated Svelte files and writes
+ * `core/journey/_utilities/custom-registry.ts`.
+ *
+ * All I/O runs in-process via the platform `FileSystem` service — no subprocess
+ * spawning. Validation errors across multiple components are collected and
+ * reported together.
+ */
+export const runRegistryScript = (projectDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const stageDir = path.join(projectDir, 'experimental', 'custom', 'stages');
+    const callbackDir = path.join(projectDir, 'experimental', 'custom', 'callbacks');
+    const registryDir = path.join(projectDir, 'core', 'journey', '_utilities', 'registry');
+    const registryPath = path.join(registryDir, 'custom-registry.ts');
+    const [stageComponents, callbackComponents] = yield* Effect.all([
+        scanDirectory(fs, path, stageDir, 'stage'),
+        scanDirectory(fs, path, callbackDir, 'callback'),
+    ], { concurrency: 'unbounded' });
+    const content = buildRegistryContent(path, registryDir, stageComponents, callbackComponents);
+    yield* fs
+        .makeDirectory(registryDir, { recursive: true })
+        .pipe(Effect.mapError((cause) => new RegistryScanError({ directory: registryDir, cause })));
+    yield* fs
+        .writeFileString(registryPath, content)
+        .pipe(Effect.mapError((cause) => new RegistryScanError({ directory: registryPath, cause })));
+    const total = stageComponents.length + callbackComponents.length;
+    if (total === 0) {
+        yield* Console.log(`custom-registry.ts generated (no custom components found — registries are empty)`);
+    }
+    else {
+        yield* Console.log(`custom-registry.ts generated:`);
+        if (stageComponents.length > 0)
+            yield* Console.log(`  Stages    (${stageComponents.length}): ${stageComponents
+                .map((c) => c.name)
+                .join(', ')}`);
+        if (callbackComponents.length > 0)
+            yield* Console.log(`  Callbacks (${callbackComponents.length}): ${callbackComponents
+                .map((c) => c.name)
+                .join(', ')}`);
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgerock/login-framework-cli",
-  "version": "0.0.0-beta-20260713173318",
+  "version": "0.0.0-beta-20260713183326",
   "description": "CLI tool for scaffolding and managing Ping Login Widget and Login App custom component projects",
   "type": "module",
   "exports": {
@@ -36,6 +36,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@effect/ai": "^0.35.0",
     "@effect/cli": "^0.75.0",
     "@effect/platform": "^0.96.0",
     "@effect/platform-node": "^0.106.0",