@forgerock/login-framework-cli 0.0.0-beta.0 → 0.1.1

package/README.md

@@ -10,13 +10,13 @@ CLI for initializing, scaffolding, and updating Ping Login Widget and Login App
 ## Installation
 
 ```sh
-npm install -g @ping-identity/login-framework-cli
+npm install -g @forgerock/login-framework-cli
 ```
 
 Or run directly without installing:
 
 ```sh
-npx @ping-identity/login-framework-cli init my-project
+npx @forgerock/login-framework-cli init my-project
 ```
 
 ## Commands
@@ -35,10 +35,10 @@ pnpm dev
 
 **Options**
 
-| Flag              | Description                                                                                                            |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `--version <tag>` | Download a specific release (e.g. `v1.2.0`). Defaults to latest.                                                       |
-| `--local <path>`  | Use a local framework directory instead of downloading from GitHub. Useful for development or air-gapped environments. |
+| Flag             | Description                                                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `--tag <tag>`    | Download a specific Git release tag (e.g. `@forgerock/login-widget@2.1.0`; legacy `v1.2.0` also works). Defaults to `main`. |
+| `--local <path>` | Use a local framework directory instead of downloading from GitHub. Useful for development or air-gapped environments.      |
 
 **What it does**
 
@@ -47,9 +47,9 @@ pnpm dev
 3. Writes a minimal `pnpm-workspace.yaml`
 4. Creates `experimental/custom/callbacks/` and `experimental/custom/stages/` with `.gitkeep` placeholders
 5. Copies the component authoring guide to `experimental/custom/README.md`
-6. Seeds an empty `core/journey/_utilities/custom-registry.ts`
-7. Injects the custom registry Vite plugin into widget and app configs
-8. Writes `.generator-version` to track the framework version in use
+6. Writes `.generator-version` to track the framework version in use
+
+The `core/journey/_utilities/registry/custom-registry.ts` file is generated by the framework's Vite plugin on the first `pnpm dev` or `pnpm build:widget` — the CLI never touches it.
 
 ---
 
@@ -57,9 +57,9 @@ pnpm dev
 
 ### `ping-lf generate stage <Name>`
 
-Scaffolds a new custom component under `experimental/custom/callbacks/<slug>/` or `experimental/custom/stages/<slug>/`, then regenerates `custom-registry.ts`.
+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
@@ -81,7 +81,7 @@ experimental/custom/callbacks/name-callback/
 └── name-callback.utilities.test.ts  # unit test stub
 ```
 
-The `@component` header in the generated `.svelte` file declares the type and name. The pre-build script and `ping-lf` both read this header to register the component:
+The `@component` header in the generated `.svelte` file declares the type and name. The framework's Vite plugin reads this header to register the component:
 
 ```svelte
 <!--
@@ -97,16 +97,75 @@ 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. Regenerates the component registry after the 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.
 
 Run from the root of an initialized project.
 
 ```sh
-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                          # update to latest
+ping-lf update --tag @forgerock/login-widget@2.1.0  # pin to a specific release tag
+ping-lf update --local ../framework     # use a local directory
+ping-lf update --directory /path/to/project  # target a specific project root
 ```
 
 **What it preserves**
@@ -139,32 +198,45 @@ my-login-project/
 
 ## Development
 
-> **All commands below must be run from the `tools/cli/` directory.**
+The CLI is a workspace package inside the framework monorepo, but it is **not** declared as a dependency of any other workspace. This is intentional: customer-generated projects must not carry a `workspace:*` link to this CLI, because that protocol only resolves inside this monorepo. The trade-off is that after a fresh clone, `ping-lf` is not on your `$PATH` until you set it up.
 
-```sh
-cd tools/cli
+### Recommended setup (once per machine)
 
-# Install dependencies
-pnpm install
+From the repo root, after `pnpm install`:
 
-# Build the CLI
-pnpm build
+```sh
+pnpm --filter @forgerock/login-framework-cli build
+pnpm --filter @forgerock/login-framework-cli link --global
+```
 
-# Run tests
-pnpm test
+`pnpm link --global` symlinks the CLI's `bin` (`tools/cli/dist/src/main.js`) into your machine's global pnpm bin directory, pointing back at this repo's `dist/`. After this, `ping-lf` works as a real command from anywhere:
 
-# Watch mode (rebuild on file changes)
-pnpm dev
+```sh
+ping-lf init my-project
+ping-lf generate callback MyCallback
+ping-lf update --tag @forgerock/login-widget@2.1.0
 ```
 
-### Running locally without installing globally
+Rebuilds (`pnpm --filter @forgerock/login-framework-cli build`) update the global binary automatically — no relink needed.
+
+To remove the global link later: `pnpm --filter @forgerock/login-framework-cli unlink --global`.
+
+### Without the global link
+
+If you'd rather not link globally, invoke the built binary directly. You still need to build first:
 
 ```sh
-# From tools/cli/ after pnpm build:
-node dist/main.js init my-project
+pnpm --filter @forgerock/login-framework-cli build
+./tools/cli/dist/src/main.js init my-project
+# or:
+pnpm --filter @forgerock/login-framework-cli exec ping-lf init my-project
+```
 
-# Or from anywhere using the full path:
-node /path/to/forgerock-web-login-framework/tools/cli/dist/main.js init my-project
+### Other useful commands
+
+```sh
+pnpm --filter @forgerock/login-framework-cli test          # run unit tests
+pnpm --filter @forgerock/login-framework-cli run dev       # tsc --watch
 ```
 
 ### Project structure
@@ -172,7 +244,8 @@ node /path/to/forgerock-web-login-framework/tools/cli/dist/main.js init my-proje
 ```
 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
@@ -180,7 +253,6 @@ tools/cli/
 │   │   └── update.ts             # ping-lf update
 │   ├── services/
 │   │   ├── file-system.ts        # copyWithExclusions
-│   │   ├── registry.ts           # component scanning + registry generation
 │   │   ├── release.ts            # GitHub release fetch
 │   │   └── vite-config.ts        # Vite plugin injection
 │   └── config/
@@ -196,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/{commands → 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 | import("../errors.js").RegistryScanError | 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/{commands → src/commands}/generate.js

@@ -1,11 +1,14 @@
 import { Args, Command, Prompt } from '@effect/cli';
 import { FileSystem, Path } from '@effect/platform';
 import { Console, Effect, Schema } from 'effect';
-import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
 import nodePath from 'node:path';
-import { runRegistryScript } from '../services/registry.js';
+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';
 /**
  * Converts a PascalCase name to a kebab-case slug.
@@ -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';
@@ -92,7 +97,9 @@ function scaffoldComponent(type, name) {
         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)
                 .replaceAll('__COMPONENT_SLUG__', slug);
             const targetPath = p.join(componentDir, targetFileName);

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

@@ -0,0 +1,16 @@
+import { Command } from '@effect/cli';
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { DirectoryConflictError, DirectoryNotEmptyError } from '../errors.js';
+import type { Option } from 'effect';
+export interface InitProjectOptions {
+    readonly directory: 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 tag: Option.Option<string>;
+}>;

package/dist/{commands → src/commands}/init.js

@@ -1,15 +1,13 @@
 import { Args, Command, Options } from '@effect/cli';
 import { FileSystem, Path } from '@effect/platform';
 import { Console, Effect } from 'effect';
-import { DirectoryConflictError, DirectoryNotEmptyError } from '../errors.js';
 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.
- * Intentionally omits `tools/` — that workspace entry exists only in the
- * upstream monorepo and is not needed (or valid) in a customer project.
  */
 const PNPM_WORKSPACE = `packages:
   - 'packages/*'
@@ -31,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.'))),
-    version: Options.optional(Options.text('version').pipe(Options.withDescription('Framework version tag to download (e.g. v1.2.0). If omitted, the main branch is used.'))),
-}, ({ directory, local, version }) => 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));
@@ -87,9 +81,13 @@ export const initCommand = Command.make('init', {
     // ── 6. Write .generator-version ────────────────────────────────────────
     yield* writeVersion(resolvedDir, {
         version: resolvedVersion,
-        commitHash: '',
         generatedAt: new Date().toISOString(),
     });
     // ── 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.'))),
+    tag: Options.optional(Options.text('tag').pipe(Options.withDescription('Framework Git release tag to download (e.g. @forgerock/login-widget@2.1.0 or v1.2.0). If omitted, the main branch is used.'))),
+}, ({ directory, local, tag }) => initProject({ directory, local, version: tag })).pipe(Command.withDescription('Bootstrap a new Ping Login Widget or Login App project from a GitHub release or a local framework path.'));

package/dist/{commands → src/commands}/source.d.ts

@@ -19,4 +19,4 @@ export declare const resolveSource: (local: Option.Option<string>, version: Opti
 } | {
     sourceDir: string;
     resolvedVersion: "local";
-}, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError, import("@effect/platform/FileSystem").FileSystem | Path.Path | Release | import("effect/Scope").Scope>;
+}, import("../errors.js").InvalidVersionError | import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseFsError, import("@effect/platform/FileSystem").FileSystem | Path.Path | import("effect/Scope").Scope | Release>;

package/dist/{commands → src/commands}/update.d.ts

@@ -1,5 +1,7 @@
 import { Command } from '@effect/cli';
+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 local: import("effect/Option").Option<string>;
-    readonly version: import("effect/Option").Option<string>;
+    readonly directory: Option.Option<string>;
+    readonly local: Option.Option<string>;
+    readonly tag: Option.Option<string>;
 }>;

package/dist/{commands → src/commands}/update.js

@@ -1,14 +1,16 @@
 import { Command, Options } from '@effect/cli';
-import { Console, Effect } from 'effect';
-import { writeVersion, assertValidProject } from '../config/version.js';
-import { copyWithExclusions } from '../services/file-system.js';
+import { Console, Effect, Option } from 'effect';
+import nodePath from 'node:path';
+import { assertValidProject, writeVersion } from '../config/version.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.'))),
-    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 }) => Effect.gen(function* () {
-    const cwd = process.cwd();
+    tag: Options.optional(Options.text('tag').pipe(Options.withDescription('Framework Git release tag to update to (e.g. @forgerock/login-widget@2.1.0 or v1.2.0). If omitted, the main branch is used.'))),
+}, ({ local, tag, 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`);
@@ -16,7 +18,7 @@ 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, version, cwd);
+        const { sourceDir, resolvedVersion } = yield* resolveSource(local, tag, cwd);
         yield* Console.log('Copying updated framework files...');
         yield* copyWithExclusions(sourceDir, cwd);
         return resolvedVersion;
@@ -27,7 +29,6 @@ export const updateCommand = Command.make('update', {
     // ── 4. Update .generator-version ──────────────────────────────────────
     yield* writeVersion(cwd, {
         version: resolvedVersion,
-        commitHash: '',
         generatedAt: new Date().toISOString(),
     });
     yield* Console.log(`\nDone. Updated from ${currentVersion.version} to ${resolvedVersion}.\n` +

package/dist/{config → src/config}/version.d.ts

@@ -1,15 +1,13 @@
-import { Effect, Schema } from 'effect';
 import { FileSystem } from '@effect/platform';
+import { Effect, Schema } from 'effect';
 import { GeneratorVersionError } from '../errors.js';
 declare const GeneratorVersionSchema: Schema.Struct<{
     version: typeof Schema.String;
-    commitHash: typeof Schema.String;
     generatedAt: typeof Schema.String;
 }>;
 export type GeneratorVersion = typeof GeneratorVersionSchema.Type;
 export declare const readVersion: (directory: string) => Effect.Effect<{
     readonly version: string;
-    readonly commitHash: string;
     readonly generatedAt: string;
 }, GeneratorVersionError | import("@effect/platform/Error").PlatformError, FileSystem.FileSystem>;
 export declare const writeVersion: (directory: string, version: GeneratorVersion) => Effect.Effect<void, import("@effect/platform/Error").PlatformError, FileSystem.FileSystem>;
@@ -20,7 +18,6 @@ export declare const writeVersion: (directory: string, version: GeneratorVersion
  */
 export declare const assertValidProject: (directory: string) => Effect.Effect<{
     readonly version: string;
-    readonly commitHash: string;
     readonly generatedAt: string;
 }, GeneratorVersionError | import("@effect/platform/Error").PlatformError, FileSystem.FileSystem>;
 export {};

package/dist/{config → src/config}/version.js

@@ -1,9 +1,8 @@
-import { Console, Effect, Schema } from 'effect';
 import { FileSystem } from '@effect/platform';
+import { Console, Effect, Schema } from 'effect';
 import { GeneratorVersionError } from '../errors.js';
 const GeneratorVersionSchema = Schema.Struct({
     version: Schema.String,
-    commitHash: Schema.String,
     generatedAt: Schema.String,
 });
 const VERSION_FILE = '.generator-version';

package/dist/src/main.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { Command } from '@effect/cli';
+import { NodeContext, NodeRuntime } from '@effect/platform-node';
+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';
+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,
+});
+// 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 tag:      ping-lf init <dir> --tag @forgerock/login-widget@2.1.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 a Git tag like @forgerock/login-widget@2.1.0 or 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, {}>;