@forgerock/login-framework-cli 0.0.0-beta-20260429204418

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2025 Ping Identity Corporation (formerly ForgeRock AS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# `ping-lf` — Ping Login Framework CLI
+
+CLI for initializing, scaffolding, and updating Ping Login Widget and Login App custom component projects.
+
+## Prerequisites
+
+- **Node.js** >= 20.0.0
+- **pnpm** >= 9
+
+## Installation
+
+```sh
+npm install -g @forgerock/login-framework-cli
+```
+
+Or run directly without installing:
+
+```sh
+npx @forgerock/login-framework-cli init my-project
+```
+
+## Commands
+
+### `ping-lf init <directory>`
+
+Bootstraps a new Login Widget or Login App project into `<directory>` by fetching the latest framework release from GitHub, copying it with safe exclusions, and setting up the custom component scaffolding.
+
+```sh
+ping-lf init my-login-project
+cd my-login-project
+pnpm install
+cp .env.example .env   # fill in your ForgeRock AM details
+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. |
+
+**What it does**
+
+1. Downloads the framework archive from GitHub Releases (or copies from `--local`)
+2. Copies framework files, excluding build artifacts, secrets, and `tools/`
+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
+
+---
+
+### `ping-lf generate callback <Name>`
+
+### `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`.
+
+Run from the root of an initialized project.
+
+```sh
+# Override the built-in NameCallback renderer
+ping-lf generate callback NameCallback
+
+# Override the DefaultLogin stage layout
+ping-lf generate stage DefaultLogin
+
+# Create a brand-new callback type (paired with a custom AM node)
+ping-lf generate callback MyTelemetryCallback
+```
+
+**What it creates** (example for `ping-lf generate callback NameCallback`):
+
+```
+experimental/custom/callbacks/name-callback/
+├── name-callback.svelte          # component implementation — edit this
+└── name-callback.utilities.ts    # helper functions (optional)
+└── 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:
+
+```svelte
+<!--
+@component
+Type: callback
+Name: NameCallback
+-->
+```
+
+Setting `Name` to an existing default (e.g. `NameCallback`, `DefaultLogin`) **overrides** that component. Setting it to a new name **extends** the framework with a custom type.
+
+See `experimental/custom/README.md` for the full prop contract.
+
+---
+
+### `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.
+
+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
+```
+
+**What it preserves**
+
+- `experimental/custom/` — all custom components are untouched
+- `pnpm-workspace.yaml` — your workspace config is not overwritten
+- `.env` files — excluded from the copy
+
+**After updating**, run `pnpm install` if the framework's package dependencies changed.
+
+---
+
+## Project layout (after `init`)
+
+```
+my-login-project/
+├── packages/login-widget/        # @forgerock/login-widget
+├── apps/login-app/               # SvelteKit dev/docs app
+├── core/                         # Shared stores, components, journey logic
+│   └── journey/_utilities/
+│       └── custom-registry.ts    # AUTO-GENERATED — do not edit
+├── experimental/
+│   └── custom/
+│       ├── README.md             # Component authoring guide
+│       ├── callbacks/            # Your custom callback components
+│       └── stages/               # Your custom stage components
+├── .generator-version            # Tracks the framework version in use
+└── pnpm-workspace.yaml
+```
+
+## Development
+
+> **All commands below must be run from the `tools/cli/` directory.**
+
+```sh
+cd tools/cli
+
+# Install dependencies
+pnpm install
+
+# Build the CLI
+pnpm build
+
+# Run tests
+pnpm test
+
+# Watch mode (rebuild on file changes)
+pnpm dev
+```
+
+### Running locally without installing globally
+
+```sh
+# From tools/cli/ after pnpm build:
+node dist/main.js 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
+```
+
+### Project structure
+
+```
+tools/cli/
+├── src/
+│   ├── main.ts                   # CLI entry point (ping-lf binary)
+│   ├── errors.ts                 # Typed Effect errors
+│   ├── commands/
+│   │   ├── init.ts               # ping-lf init
+│   │   ├── generate.ts           # ping-lf generate callback|stage
+│   │   └── 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/
+│       ├── exclusions.ts         # Files/dirs excluded from copy operations
+│       └── version.ts            # .generator-version read/write
+├── templates/
+│   ├── callback/                 # Scaffold templates for callbacks
+│   └── stage/                    # Scaffold templates for stages
+└── test/                         # Vitest unit tests
+```
+
+### Tech stack
+
+- **[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/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/scripts/generate-registry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/generate-registry.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Thin Effect runner for generating the custom component registry.
+ *
+ * Called by:
+ *  - packages/login-widget/package.json  "prebuild"
+ *  - Root package.json                    "generate:registry"
+ *
+ * Requires the CLI to be compiled first:
+ *   pnpm --filter @forgerock/login-framework-cli run build
+ */
+import { Effect } from 'effect';
+import { NodeContext, NodeRuntime } from '@effect/platform-node';
+const { runRegistryScript } = await import('../src/services/registry.js');
+const projectDir = process.argv[2];
+if (!projectDir) {
+    console.error('Usage: node generate-registry.mjs <projectDir>');
+    process.exit(1);
+}
+NodeRuntime.runMain(runRegistryScript(projectDir).pipe(Effect.provide(NodeContext.layer)));

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

@@ -0,0 +1,28 @@
+import { Command } from '@effect/cli';
+import { FileSystem, Path } from '@effect/platform';
+import { Schema } from 'effect';
+import { ComponentAlreadyExistsError, InvalidComponentNameError } from '../errors.js';
+/**
+ * Validates a callback component name: must be a valid name (PascalCase, alphanumeric only).
+ * Callback names are driven by AM's callback type strings (e.g. NameCallback, PasswordCallback).
+ */
+export declare const CallbackNameSchema: Schema.transform<Schema.filter<typeof Schema.String>, Schema.Struct<{
+    name: typeof Schema.String;
+    slug: typeof Schema.String;
+}>>;
+/**
+ * Validates a stage component name: accepts any string that is safe for a directory name and
+ * HTML comment embedding. Stage names in AM are arbitrary strings set on the Page Node — there
+ * is no name constraint, unlike callbacks.
+ */
+export declare const StageNameSchema: Schema.transform<Schema.filter<typeof Schema.String>, Schema.Struct<{
+    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, {
+    readonly subcommand: import("effect/Option").Option<{
+        readonly name: string;
+    } | {
+        readonly name: string;
+    }>;
+}>;

package/dist/src/commands/generate.js

@@ -0,0 +1,137 @@
+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 nodePath from 'node:path';
+import { runRegistryScript } from '../services/registry.js';
+import { assertValidProject } from '../config/version.js';
+import { ComponentAlreadyExistsError, InvalidComponentNameError } from '../errors.js';
+const CUSTOM_DIR = 'experimental/custom';
+/**
+ * Converts a PascalCase name to a kebab-case slug.
+ * Uses two passes to correctly handle acronyms.
+ * Examples: "MyCallback" → "my-callback", "JWTLogin" → "jwt-login", "MyURLCallback" → "my-url-callback"
+ */
+function toKebabCase(name) {
+    return name
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .replace(/([a-z\d])([A-Z])/g, '$1-$2')
+        .toLowerCase();
+}
+/**
+ * Converts an arbitrary string to a kebab-case directory slug.
+ * Used for stage names which may contain spaces, hyphens, or mixed case.
+ * Examples: "My Login Stage" → "my-login-stage", "DefaultLogin" → "defaultlogin", "OTP Login" → "otp-login"
+ */
+function toSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Validates a callback component name: must be a valid name (PascalCase, alphanumeric only).
+ * Callback names are driven by AM's callback type strings (e.g. NameCallback, PasswordCallback).
+ */
+export const CallbackNameSchema = Schema.String.pipe(Schema.filter((s) => /^[A-Z][A-Za-z0-9]+$/.test(s)), Schema.transform(Schema.Struct({ name: Schema.String, slug: Schema.String }), {
+    strict: true,
+    decode: (name) => ({ name, slug: toKebabCase(name) }),
+    encode: ({ name }) => name,
+}));
+/**
+ * Validates a stage component name: accepts any string that is safe for a directory name and
+ * HTML comment embedding. Stage names in AM are arbitrary strings set on the Page Node — there
+ * is no name constraint, unlike callbacks.
+ */
+export const StageNameSchema = Schema.String.pipe(Schema.filter((s) => s.length >= 2 &&
+    /[A-Za-z]/.test(s) &&
+    !s.includes('\0') &&
+    !/[\n\r]/.test(s) &&
+    !/^\.\.?[/\\]/.test(s)), Schema.transform(Schema.Struct({ name: Schema.String, slug: Schema.String }), {
+    strict: true,
+    decode: (name) => ({ name, slug: toSlug(name) }),
+    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/.
+ */
+function getTemplatesDir() {
+    const __dirname = nodePath.dirname(fileURLToPath(import.meta.url));
+    return nodePath.join(__dirname, '../templates');
+}
+function scaffoldComponent(type, name) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const p = yield* Path.Path;
+        // ── Guard: validate component name format ─────────────────────────────
+        // Callbacks must be valid  name (PascalCase, alphanumeric only).
+        // 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();
+        // ── Guard: must be run from an initialized project root ───────────────
+        yield* assertValidProject(cwd);
+        const subDir = type === 'callback' ? 'callbacks' : 'stages';
+        const componentDir = p.join(cwd, CUSTOM_DIR, subDir, slug);
+        const templatesDir = p.join(getTemplatesDir(), type);
+        // ── Guard: prevent overwriting an existing component ──────────────────
+        const exists = yield* fs.exists(componentDir);
+        if (exists) {
+            yield* Effect.fail(new ComponentAlreadyExistsError({ path: componentDir }));
+        }
+        yield* Console.log(`\nGenerating ${type} component: ${name}\n`);
+        // ── Create component directory ─────────────────────────────────────────
+        yield* fs.makeDirectory(componentDir, { recursive: true });
+        // ── Copy and process template files ───────────────────────────────────
+        // 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 processedContent = sourceContent
+                .replaceAll('__COMPONENT_NAME__', name)
+                .replaceAll('__COMPONENT_SLUG__', slug);
+            const targetPath = p.join(componentDir, targetFileName);
+            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((f) => `  ${f}`).join('\n') +
+            `\n\nNext: open ${p.join(componentDir, `${slug}.svelte`)} and implement your component.\n`);
+    });
+}
+// ── Subcommands ──────────────────────────────────────────────────────────────
+const generateCallbackCommand = Command.make('callback', {
+    name: Args.text({ name: 'Name' }).pipe(Args.withDescription('PascalCase component name (e.g. MyCallback). Must match the callback type string your AM node sends.')),
+}, ({ name }) => scaffoldComponent('callback', name)).pipe(Command.withDescription('Scaffold a new custom callback component under experimental/custom/callbacks/.'));
+const generateStageCommand = Command.make('stage', {
+    name: Args.text({ name: 'Name' }).pipe(Args.withDescription('Stage name as configured on your AM journey Page Node (e.g. "DefaultLogin" or "My Login Stage"). Any non-empty string is accepted — stage names in AM are arbitrary and not constrained to PascalCase.')),
+}, ({ name }) => scaffoldComponent('stage', name)).pipe(Command.withDescription('Scaffold a new custom stage component under experimental/custom/stages/.'));
+export const generateCommand = Command.make('generate', {}, () => Effect.gen(function* () {
+    const type = yield* Prompt.select({
+        message: 'Select component type',
+        choices: [
+            {
+                title: 'callback',
+                value: 'callback',
+                description: 'Custom AM callback renderer',
+            },
+            { title: 'stage', value: 'stage', description: 'Custom journey stage layout' },
+        ],
+    });
+    const name = yield* Prompt.text({
+        message: type === 'callback'
+            ? 'Callback name (PascalCase name, e.g. MyCallback)'
+            : 'Stage name (as set on your AM Page Node, e.g. DefaultLogin or My Login Stage)',
+    });
+    yield* scaffoldComponent(type, name);
+})).pipe(Command.withDescription('Scaffold a new custom callback or stage component from a template.'), Command.withSubcommands([generateCallbackCommand, generateStageCommand]));

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

@@ -0,0 +1,8 @@
+import { Command } from '@effect/cli';
+import { FileSystem, Path } from '@effect/platform';
+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 | import("../errors.js").RegistryScanError | DirectoryConflictError | DirectoryNotEmptyError | import("@effect/platform/Error").PlatformError, {
+    readonly directory: string;
+    readonly local: import("effect/Option").Option<string>;
+    readonly version: import("effect/Option").Option<string>;
+}>;

package/dist/src/commands/init.js

@@ -0,0 +1,95 @@
+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 { 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/*'
+  - 'apps/*'
+  - 'e2e'
+`;
+const nextStepsMessage = (dir) => `
+Done. Project initialized successfully.
+
+Next steps:
+  cd ${dir}
+  pnpm install
+  cp .env.example .env    # add your ForgeRock AM connection details
+  pnpm dev
+
+To scaffold your first custom component:
+  ping-lf generate callback MyCallback
+  ping-lf generate stage MyStage
+
+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* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const resolvedDir = path.resolve(expandTilde(directory));
+    yield* Console.log(`\nInitializing Ping Login Widget / Login App project in: ${resolvedDir}\n`);
+    // ── 0. Validate target directory ──────────────────────────────────────
+    const dirExists = yield* fs.exists(resolvedDir);
+    if (dirExists) {
+        const isFramework = yield* isFrameworkDirectory(resolvedDir);
+        if (isFramework) {
+            yield* Effect.fail(new DirectoryConflictError({ path: resolvedDir }));
+        }
+        const entries = yield* fs
+            .readDirectory(resolvedDir)
+            .pipe(Effect.orElseSucceed(() => []));
+        if (entries.length > 0) {
+            yield* Effect.fail(new DirectoryNotEmptyError({ path: resolvedDir }));
+        }
+    }
+    // ── 1. Resolve source + copy framework (scoped: temp dir auto-cleaned) ──
+    // 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, resolvedDir);
+        // ── 2. Create target directory + copy framework (with exclusions) ──
+        yield* Console.log('Copying framework files...');
+        yield* fs.makeDirectory(resolvedDir, { recursive: true });
+        yield* copyWithExclusions(sourceDir, resolvedDir);
+        return resolvedVersion;
+    }));
+    // ── 3. Write pnpm-workspace.yaml (omits tools/ present in upstream) ────
+    yield* fs.writeFileString(path.join(resolvedDir, 'pnpm-workspace.yaml'), PNPM_WORKSPACE);
+    // ── 4. Scaffold experimental/custom/ ──────────────────────────────────
+    // copyWithExclusions already copies experimental/custom/demo/,
+    // login-framework.ts, README.md, and tsconfig.json from the source.
+    // Only callbacks/ and stages/ are protected (they hold user components).
+    // Create them as empty dirs with .gitkeep — components come via `ping-lf generate`.
+    yield* Console.log('Scaffolding custom component directories...');
+    yield* Effect.forEach(['callbacks', 'stages'], (dir) => Effect.gen(function* () {
+        const customDir = path.join(resolvedDir, 'experimental', 'custom', dir);
+        yield* fs.makeDirectory(customDir, { recursive: true });
+        yield* fs.writeFileString(path.join(customDir, '.gitkeep'), '');
+    }), { concurrency: 'unbounded', discard: true });
+    // ── 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,
+        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.'));

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

@@ -0,0 +1,3 @@
+import { Command } from '@effect/cli';
+import { Release } from '../services/release.js';
+export declare const releasesCommand: Command.Command<"releases", Release, import("../errors.js").ReleaseNetworkError | import("../errors.js").ReleaseParseError | import("../errors.js").ReleaseNotFoundError, {}>;

package/dist/src/commands/releases.js

@@ -0,0 +1,12 @@
+import { Command } from '@effect/cli';
+import { Console, Effect } from 'effect';
+import { Release } from '../services/release.js';
+export const releasesCommand = Command.make('releases', {}, () => Effect.gen(function* () {
+    const release = yield* Release;
+    const releases = yield* release.listReleases();
+    yield* Console.log('\nAvailable Login Framework releases:\n');
+    for (const { tag, publishedAt } of releases) {
+        yield* Console.log(`  ${tag.padEnd(10)} ${publishedAt}`);
+    }
+    yield* Console.log('');
+})).pipe(Command.withDescription('List available Login Framework releases from GitHub.'));

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

@@ -0,0 +1,22 @@
+import { Path } from '@effect/platform';
+import { Effect, Option } from 'effect';
+import { Release } from '../services/release.js';
+/**
+ * Resolves the framework source directory and version from a local path or a
+ * GitHub release download.  Shared by `init` and `update` commands.
+ *
+ * @param local   - Optional local framework directory path.
+ * @param version - Optional explicit release version tag.
+ * @param targetDir - Directory that will receive the downloaded release temp
+ *                    folder (`.framework-tmp`).
+ */
+export declare const resolveSource: (local: Option.Option<string>, version: Option.Option<string>, targetDir: string) => Effect.Effect<{
+    sourceDir: string;
+    resolvedVersion: "main";
+} | {
+    sourceDir: string;
+    resolvedVersion: string;
+} | {
+    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>;

package/dist/src/commands/source.js

@@ -0,0 +1,24 @@
+import { Path } from '@effect/platform';
+import { Console, Effect, Option, pipe } from 'effect';
+import { expandTilde } from '../services/file-system.js';
+import { Release } from '../services/release.js';
+/**
+ * Resolves the framework source directory and version from a local path or a
+ * GitHub release download.  Shared by `init` and `update` commands.
+ *
+ * @param local   - Optional local framework directory path.
+ * @param version - Optional explicit release version tag.
+ * @param targetDir - Directory that will receive the downloaded release temp
+ *                    folder (`.framework-tmp`).
+ */
+export const resolveSource = (local, version, targetDir) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const release = yield* Release;
+    return yield* Option.match(local, {
+        onSome: (localPath) => pipe(Effect.sync(() => path.resolve(expandTilde(localPath))), Effect.tap((dir) => Console.log(`Using local source: ${dir}`)), Effect.map((dir) => ({ sourceDir: dir, resolvedVersion: 'local' }))),
+        onNone: () => pipe(Option.match(version, {
+            onSome: (v) => pipe(Effect.tap(Effect.succeed(v), (v) => Console.log(`Fetching framework version: ${v}...`)), Effect.flatMap((v) => pipe(release.fetch(v, targetDir), Effect.map((sourceDir) => ({ sourceDir, resolvedVersion: v }))))),
+            onNone: () => pipe(Console.log('Fetching framework from main branch...'), Effect.flatMap(() => release.fetchBranch('main', targetDir)), Effect.map((sourceDir) => ({ sourceDir, resolvedVersion: 'main' }))),
+        })),
+    });
+});

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

@@ -0,0 +1,5 @@
+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("../errors.js").RegistryScanError | import("@effect/platform/Error").PlatformError, {
+    readonly local: import("effect/Option").Option<string>;
+    readonly version: import("effect/Option").Option<string>;
+}>;

package/dist/src/commands/update.js

@@ -0,0 +1,36 @@
+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 { runRegistryScript } from '../services/registry.js';
+import { resolveSource } from './source.js';
+export const updateCommand = Command.make('update', {
+    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();
+    // ── 1. Verify this is an initialized project ──────────────────────────
+    const currentVersion = yield* assertValidProject(cwd);
+    yield* Console.log(`\nUpdating project from version: ${currentVersion.version}\n`);
+    // ── 2. Resolve source + copy framework (scoped: temp dir auto-cleaned) ──
+    // 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);
+        yield* Console.log('Copying updated framework files...');
+        yield* copyWithExclusions(sourceDir, cwd);
+        return resolvedVersion;
+    }));
+    // ── 3. Regenerate custom-registry.ts ──────────────────────────────────
+    yield* Console.log('Regenerating custom component registry...');
+    yield* runRegistryScript(cwd);
+    // ── 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` +
+        '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/config/exclusions.d.ts

@@ -0,0 +1 @@
+export declare function isExcluded(relativePath: string): boolean;