@forgerock/login-framework-cli 0.0.0-beta-20261013223421 → 0.0.0-beta-20261021173425

package/README.md

@@ -45,11 +45,11 @@ pnpm dev
 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
+4. Creates `experimental/custom/callbacks/` and `experimental/custom/stages/` with `.gitkeep` placeholders, and places the page header and footer wrapper files `experimental/custom/header/header.svelte` and `experimental/custom/footer/footer.svelte`
 5. Copies the component authoring guide to `experimental/custom/README.md`
 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.
+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 generates it. (With `--local`, the bulk copy carries over whatever `custom-registry.ts` exists in the local source; the Vite plugin regenerates it on the next build.)
 
 ---
 
@@ -93,6 +93,8 @@ 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.
 
+Page headers and footers are not scaffolded with `generate`: they are fixed wrapper files (`experimental/custom/header/header.svelte` and `experimental/custom/footer/footer.svelte`), generated on first build by the framework's Vite plugin and never overwritten once they exist. Edit the wrappers directly.
+
 See `experimental/custom/README.md` for the full prop contract.
 
 ---
@@ -171,6 +173,7 @@ ping-lf update --directory /path/to/project  # target a specific project root
 **What it preserves**
 
 - `experimental/custom/` — all custom components are untouched
+- The header and footer wrapper files are never overwritten — `update` only backfills ones that are missing, so your edits survive
 - `pnpm-workspace.yaml` — your workspace config is not overwritten
 - `.env` files — excluded from the copy
 
@@ -191,7 +194,9 @@ my-login-project/
 │   └── custom/
 │       ├── README.md             # Component authoring guide
 │       ├── callbacks/            # Your custom callback components
-│       └── stages/               # Your custom stage components
+│       ├── stages/               # Your custom stage components
+│       ├── header/header.svelte  # Page header wrapper (placed by init; regenerated by the plugin if deleted)
+│       └── footer/footer.svelte  # Page footer wrapper (placed by init; regenerated by the plugin if deleted)
 ├── .generator-version            # Tracks the framework version in use
 └── pnpm-workspace.yaml
 ```

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

@@ -19,11 +19,21 @@ export declare const StageNameSchema: Schema.transform<Schema.filter<typeof Sche
     name: typeof Schema.String;
     slug: typeof Schema.String;
 }>>;
-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, {
+/**
+ * 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.
+ */
+export declare function getTemplatesDir(): string;
+/** Supported custom component types for scaffolding. */
+type ScaffoldType = 'callback' | 'stage';
+export declare function scaffoldComponent(type: ScaffoldType, name: string, directory?: string): Effect.Effect<void, import("../errors.js").GeneratorVersionError | InvalidComponentNameError | ComponentAlreadyExistsError | 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("@effect/platform/Error").PlatformError | import("@effect/platform/Terminal").QuitException, {
     readonly subcommand: import("effect/Option").Option<{
         readonly name: string;
     } | {
         readonly name: string;
     }>;
 }>;
+export {};

package/dist/src/commands/generate.js

@@ -7,7 +7,6 @@ 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';
 /**
@@ -66,7 +65,7 @@ export const StageNameSchema = Schema.String.pipe(Schema.filter((s) => s.length
  * 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() {
+export function getTemplatesDir() {
     const __dirname = nodePath.dirname(fileURLToPath(import.meta.url));
     const compiledPath = nodePath.join(__dirname, '../templates');
     return existsSync(compiledPath) ? compiledPath : nodePath.join(__dirname, '../../templates');
@@ -77,14 +76,17 @@ export function scaffoldComponent(type, name, directory) {
         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.
+        // Stages are arbitrary 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 = p.resolve(expandTilde(directory ?? 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 subDirs = {
+            callback: 'callbacks',
+            stage: 'stages',
+        };
+        const componentDir = p.join(cwd, CUSTOM_DIR, subDirs[type], slug);
         const templatesDir = p.join(getTemplatesDir(), type);
         // ── Guard: prevent overwriting an existing component ──────────────────
         const exists = yield* fs.exists(componentDir);
@@ -111,10 +113,10 @@ export function scaffoldComponent(type, name, directory) {
             yield* fs.writeFileString(targetPath, processedContent);
             createdFiles.push(targetPath);
         }
-        // ── Regenerate custom-registry.ts ────────────────────────────────────
-        yield* Console.log('Regenerating custom component registry...');
-        yield* runRegistryScript(cwd);
         // ── Print summary ──────────────────────────────────────────────────────
+        // custom-registry.ts is NOT regenerated here — the framework's Vite plugin
+        // picks the new component up on the next build or dev-server start (and,
+        // in dev, watches these directories for adds/removals without a restart).
         yield* Console.log(`Done. ${type} component scaffolded successfully.\n\n` +
             `Files created:\n` +
             createdFiles.map((f) => `  ${f}`).join('\n') +

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

@@ -3,13 +3,18 @@ import { FileSystem, Path } from '@effect/platform';
 import { Effect } from 'effect';
 import { DirectoryConflictError, DirectoryNotEmptyError } from '../errors.js';
 import type { Option } from 'effect';
+/**
+ * Custom component directories scaffolded (with .gitkeep) at project init.
+ * Protected during `ping-lf update` — see PROTECTED_DIRS in services/file-system.
+ */
+export declare const CUSTOM_COMPONENT_DIRS: readonly ["callbacks", "stages"];
 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, {
+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("@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("@effect/platform/Error").PlatformError, {
     readonly directory: string;
     readonly local: Option.Option<string>;
     readonly tag: Option.Option<string>;

package/dist/src/commands/init.js

@@ -3,8 +3,8 @@ import { FileSystem, Path } from '@effect/platform';
 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 { copyWithExclusions, copyWrapperFiles, expandTilde, isFrameworkDirectory, } from '../services/file-system.js';
+import { getTemplatesDir } from './generate.js';
 import { resolveSource } from './source.js';
 /**
  * Minimal pnpm-workspace.yaml written to the customer project.
@@ -14,6 +14,11 @@ const PNPM_WORKSPACE = `packages:
   - 'apps/*'
   - 'e2e'
 `;
+/**
+ * Custom component directories scaffolded (with .gitkeep) at project init.
+ * Protected during `ping-lf update` — see PROTECTED_DIRS in services/file-system.
+ */
+export const CUSTOM_COMPONENT_DIRS = ['callbacks', 'stages'];
 const nextStepsMessage = (dir) => `
 Done. Project initialized successfully.
 
@@ -57,6 +62,12 @@ export const initProject = ({ directory, local, version }) => Effect.gen(functio
         yield* Console.log('Copying framework files...');
         yield* fs.makeDirectory(resolvedDir, { recursive: true });
         yield* copyWithExclusions(sourceDir, resolvedDir);
+        // ── 2b. Place the framework-shipped wrapper files ──────────────────
+        // The bulk copy skips them (they are file-protected: customer edits
+        // to them must survive `update`), so init places them explicitly from
+        // the CLI's own wrapper templates. The app's +page.svelte imports them
+        // directly, so a project without them cannot build.
+        yield* copyWrapperFiles(resolvedDir, getTemplatesDir());
         return resolvedVersion;
     }));
     // ── 3. Write pnpm-workspace.yaml (omits tools/ present in upstream) ────
@@ -64,26 +75,20 @@ export const initProject = ({ directory, local, version }) => Effect.gen(functio
     // ── 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).
+    // Only the custom component dirs 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* () {
+    yield* Effect.forEach(CUSTOM_COMPONENT_DIRS, (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 ────────────────────────────────────────
+    // ── 5. Write .generator-version ────────────────────────────────────────
     yield* writeVersion(resolvedDir, {
         version: resolvedVersion,
         generatedAt: new Date().toISOString(),
     });
-    // ── 7. Print next steps ───────────────────────────────────────────────
+    // ── 6. Print next steps ───────────────────────────────────────────────
     yield* Console.log(nextStepsMessage(directory));
 });
 export const initCommand = Command.make('init', {

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

@@ -1,6 +1,12 @@
 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, {
+import { Effect, Option } from 'effect';
+export interface UpdateProjectOptions {
+    readonly directory: Option.Option<string>;
+    readonly local: Option.Option<string>;
+    readonly tag: Option.Option<string>;
+}
+export declare const updateProject: ({ directory, local, tag }: UpdateProjectOptions) => Effect.Effect<void, 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, import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path | import("../services/release.js").Release>;
+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 directory: Option.Option<string>;
     readonly local: Option.Option<string>;
     readonly tag: Option.Option<string>;

package/dist/src/commands/update.js

@@ -2,14 +2,10 @@ import { Command, Options } from '@effect/cli';
 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 { copyWithExclusions, copyWrapperFiles, expandTilde } from '../services/file-system.js';
+import { getTemplatesDir } from './generate.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 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* () {
+export const updateProject = ({ directory, local, tag }) => 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);
@@ -21,17 +17,28 @@ export const updateCommand = Command.make('update', {
         const { sourceDir, resolvedVersion } = yield* resolveSource(local, tag, cwd);
         yield* Console.log('Copying updated framework files...');
         yield* copyWithExclusions(sourceDir, cwd);
+        // ── 2b. Backfill missing wrapper files ─────────────────────────────
+        // The bulk copy skips them (they are file-protected so customer edits
+        // survive), but a project updated from an older framework version may
+        // not have them yet — the app's +page.svelte imports them directly, so
+        // a project missing one cannot build. copyWrapperFiles copies only
+        // absent files, from the CLI's own wrapper templates, never
+        // overwriting customer edits.
+        yield* copyWrapperFiles(cwd, getTemplatesDir());
         return resolvedVersion;
     }));
-    // ── 3. Regenerate custom-registry.ts ──────────────────────────────────
-    yield* Console.log('Regenerating custom component registry...');
-    yield* runRegistryScript(cwd);
-    // ── 4. Update .generator-version ──────────────────────────────────────
+    // ── 3. Update .generator-version ──────────────────────────────────────
+    // custom-registry.ts is NOT regenerated here — the framework's Vite
+    // plugin regenerates it on the next build or dev-server start.
     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/.'));
+});
+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 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.'))),
+}, updateProject).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,12 +79,4 @@ 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,5 +21,3 @@ export class InvalidComponentNameError extends Data.TaggedError('InvalidComponen
 }
 export class ComponentAlreadyExistsError extends Data.TaggedError('ComponentAlreadyExistsError') {
 }
-export class RegistryScanError extends Data.TaggedError('RegistryScanError') {
-}

package/dist/src/mcp.js

@@ -10,7 +10,6 @@ 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));
@@ -38,8 +37,6 @@ function formatError(cause) {
                 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':
@@ -158,7 +155,6 @@ const handlerLayer = mcpToolkit.toLayer({
             yield* copyWithExclusions(sourceDir, cwd);
             return resolvedVersion;
         }));
-        yield* runRegistryScript(cwd);
         yield* writeVersion(cwd, {
             version: resolvedVersion,
             generatedAt: new Date().toISOString(),

package/dist/src/services/file-system.d.ts

@@ -1,4 +1,4 @@
-import { FileSystem } from '@effect/platform';
+import { FileSystem, Path } from '@effect/platform';
 import { Effect } from 'effect';
 import { FileSystemError } from '../errors.js';
 /**
@@ -8,6 +8,37 @@ import { FileSystemError } from '../errors.js';
  * that the directory was created by `ping-lf init`.
  */
 export declare const isFrameworkDirectory: (dir: string) => Effect.Effect<boolean, never, FileSystem.FileSystem>;
+/**
+ * Framework-shipped custom wrapper files. Each is a fixed, user-editable file
+ * rendered by the login app (`+page.svelte` imports it directly). The bulk
+ * copy skips them so `update` can never overwrite customer edits;
+ * `copyWrapperFiles` backfills any the target is missing from the CLI's own
+ * wrapper templates (see WRAPPER_TEMPLATE_ELEMENTS) so a project updated onto
+ * a framework version whose app imports the wrappers still gets the defaults.
+ */
+export declare const CUSTOM_WRAPPER_FILES: readonly ["experimental/custom/header/header.svelte", "experimental/custom/footer/footer.svelte"];
+/**
+ * The page elements that ship a wrapper file. `copyWrapperFiles` copies
+ * `templates/wrapper/<element>.svelte` (the CLI's own shipped templates,
+ * resolved like the callback/stage scaffold templates) into
+ * `experimental/custom/<element>/<element>.svelte`.
+ *
+ * The CLI never reads the framework's `core/` tree — build-time vs. runtime
+ * boundary — so it owns copies of the wrapper templates instead of importing
+ * the framework's `core/.../wrapper-templates/`. The per-element order
+ * matches CUSTOM_WRAPPER_FILES.
+ */
+export declare const WRAPPER_TEMPLATE_ELEMENTS: readonly ["header", "footer"];
 /** Expand a leading `~` to the user's home directory. */
 export declare function expandTilde(p: string): string;
 export declare const copyWithExclusions: (sourceDir: string, targetDir: string) => Effect.Effect<void, FileSystemError, FileSystem.FileSystem>;
+/**
+ * Backfills the framework-shipped wrapper files into `targetDir`, skipping any
+ * the target already has. Customer edits are never overwritten — a file is
+ * copied only when absent. The copy reads from the CLI's own wrapper templates
+ * (`templates/wrapper/`, passed as `templatesDir`), mirroring the
+ * callback/stage scaffold templates. A missing template is a no-op, which
+ * keeps older CLI versions (whose paired framework app does not import
+ * wrappers) safe.
+ */
+export declare const copyWrapperFiles: (targetDir: string, templatesDir: string) => Effect.Effect<void, FileSystemError, FileSystem.FileSystem | Path.Path>;

package/dist/src/services/file-system.js

@@ -1,4 +1,4 @@
-import { FileSystem } from '@effect/platform';
+import { FileSystem, Path } from '@effect/platform';
 import { Effect } from 'effect';
 import path from 'node:path';
 import { isExcluded } from '../config/exclusions.js';
@@ -23,6 +23,30 @@ export const isFrameworkDirectory = Effect.fnUntraced(function* (dir) {
     return hasPkgJson && (hasExperimental || hasPnpmWorkspace);
 });
 const PROTECTED_DIRS = ['experimental/custom/callbacks/', 'experimental/custom/stages/'];
+/**
+ * Framework-shipped custom wrapper files. Each is a fixed, user-editable file
+ * rendered by the login app (`+page.svelte` imports it directly). The bulk
+ * copy skips them so `update` can never overwrite customer edits;
+ * `copyWrapperFiles` backfills any the target is missing from the CLI's own
+ * wrapper templates (see WRAPPER_TEMPLATE_ELEMENTS) so a project updated onto
+ * a framework version whose app imports the wrappers still gets the defaults.
+ */
+export const CUSTOM_WRAPPER_FILES = [
+    'experimental/custom/header/header.svelte',
+    'experimental/custom/footer/footer.svelte',
+];
+/**
+ * The page elements that ship a wrapper file. `copyWrapperFiles` copies
+ * `templates/wrapper/<element>.svelte` (the CLI's own shipped templates,
+ * resolved like the callback/stage scaffold templates) into
+ * `experimental/custom/<element>/<element>.svelte`.
+ *
+ * The CLI never reads the framework's `core/` tree — build-time vs. runtime
+ * boundary — so it owns copies of the wrapper templates instead of importing
+ * the framework's `core/.../wrapper-templates/`. The per-element order
+ * matches CUSTOM_WRAPPER_FILES.
+ */
+export const WRAPPER_TEMPLATE_ELEMENTS = ['header', 'footer'];
 /** Expand a leading `~` to the user's home directory. */
 export function expandTilde(p) {
     if (p === '~' || p.startsWith('~/') || p.startsWith('~\\')) {
@@ -33,7 +57,8 @@ export function expandTilde(p) {
 }
 function isProtected(relativePath) {
     const normalized = normalizeSeparators(relativePath);
-    return PROTECTED_DIRS.some((dir) => `${normalized}/`.startsWith(dir));
+    return (PROTECTED_DIRS.some((dir) => `${normalized}/`.startsWith(dir)) ||
+        CUSTOM_WRAPPER_FILES.includes(normalized));
 }
 const walk = (fs, sourceDir, targetDir, dir) => Effect.gen(function* () {
     const entries = yield* fs.readDirectory(dir).pipe(wrapFsCall('readDirectory', dir));
@@ -62,3 +87,40 @@ export const copyWithExclusions = (sourceDir, targetDir) => Effect.gen(function*
     const fs = yield* FileSystem.FileSystem;
     yield* walk(fs, sourceDir, targetDir, sourceDir);
 });
+/**
+ * Backfills the framework-shipped wrapper files into `targetDir`, skipping any
+ * the target already has. Customer edits are never overwritten — a file is
+ * copied only when absent. The copy reads from the CLI's own wrapper templates
+ * (`templates/wrapper/`, passed as `templatesDir`), mirroring the
+ * callback/stage scaffold templates. A missing template is a no-op, which
+ * keeps older CLI versions (whose paired framework app does not import
+ * wrappers) safe.
+ */
+export const copyWrapperFiles = (targetDir, templatesDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    yield* Effect.forEach(
+    // Pair each wrapper target element with its template source. Positional
+    // zip on two pinned constants: the contract test pins both arrays and
+    // their per-element order, so an accidental desync fails the build.
+    WRAPPER_TEMPLATE_ELEMENTS.map((element, index) => ({
+        element,
+        wrapperPath: CUSTOM_WRAPPER_FILES[index],
+    })), ({ element, wrapperPath }) => Effect.gen(function* () {
+        const sourcePath = path.join(templatesDir, 'wrapper', `${element}.svelte`);
+        const targetPath = path.join(targetDir, wrapperPath);
+        const hasSource = yield* fs.exists(sourcePath).pipe(Effect.orElseSucceed(() => false));
+        if (!hasSource) {
+            return;
+        }
+        const hasTarget = yield* fs.exists(targetPath).pipe(Effect.orElseSucceed(() => false));
+        if (hasTarget) {
+            return;
+        }
+        const parentDir = path.dirname(targetPath);
+        yield* fs
+            .makeDirectory(parentDir, { recursive: true })
+            .pipe(wrapFsCall('makeDirectory', parentDir));
+        yield* fs.copyFile(sourcePath, targetPath).pipe(wrapFsCall('copyFile', sourcePath));
+    }), { concurrency: 'unbounded', discard: true });
+});

package/dist/src/templates/wrapper/footer.svelte

@@ -0,0 +1,68 @@
+<!--
+  Custom page footer wrapper.
+  ─────────────────────────────
+  This is your file: the framework renders it below the journey container
+  (inside the root div of the login app's +page.svelte). It is never
+  overwritten once it exists — not by rebuilds, not by `ping-lf update` — so
+  edit it freely; your changes survive framework upgrades. If you ever delete
+  it, the next build or dev-server start regenerates the default (only when
+  the file is absent; your edits are never touched).
+
+  HOW IT RENDERS
+  ──────────────
+  The footer mounts client-side only: it first renders once a journey step
+  arrives, then stays mounted for the rest of the session (no flicker while
+  steps load, switch journeys, or redirect on completion).
+
+  PROPS
+  ─────
+  The wrapper receives exactly one prop:
+
+    journeyName: string
+      Name of the journey currently driving the page (e.g. "Login",
+      "Register"). `''` means the AM default journey — the one the tenant
+      serves when the URL names no journey. Show your default-journey view
+      in that case; the footer always renders something.
+
+  The framework passes no other props. Do not add required props of your own —
+  they will arrive undefined. Anything you need beyond `journeyName`, derive
+  inside this component from the framework exports.
+-->
+
+<script lang="ts">
+  // ─── Framework imports ──────────────────────────────────────────────────────
+  /**
+   * Import everything you need from '$login-framework' — the
+   * framework's centralized exports for custom components. No need to reach
+   * into internal aliases like $core, $components, or $journey directly.
+   *
+   * Available exports (see experimental/custom/login-framework.ts for the full list).
+   */
+  import type { CustomWrapperProps } from '$login-framework';
+
+  /** The one prop the framework passes: the active journey name (`''` = default). */
+  export let journeyName: CustomWrapperProps['journeyName'] = '';
+</script>
+
+<!--
+  Default markup: neutral no-op placeholder. Replace it with your own branding.
+
+  Example — branch the markup on the prop value. Render the copyright line
+  plus "Create your account" when journeyName is "Register", the plain
+  copyright line when it is the empty string (that is the AM default journey,
+  the case where the URL named no journey), and a journeyName-suffixed
+  copyright line otherwise. In Svelte that is an if/else if/else chain on
+  journeyName.
+
+  All Tailwind classes use the framework's tw_ prefix so theme compilation
+  picks them up (see themes/default/config.cjs — prefix: 'tw_').
+-->
+<footer class="tw_hidden"></footer>
+
+<!--
+  Scoped styles for this wrapper. They apply only here — they won't leak to the
+  rest of the widget.
+-->
+<style>
+  /* Add your custom footer styles here. */
+</style>

package/dist/src/templates/wrapper/header.svelte

@@ -0,0 +1,67 @@
+<!--
+  Custom page header wrapper.
+  ─────────────────────────────
+  This is your file: the framework renders it above the journey container
+  (inside the root div of the login app's +page.svelte). It is never
+  overwritten once it exists — not by rebuilds, not by `ping-lf update` — so
+  edit it freely; your changes survive framework upgrades. If you ever delete
+  it, the next build or dev-server start regenerates the default (only when
+  the file is absent; your edits are never touched).
+
+  HOW IT RENDERS
+  ──────────────
+  The header mounts client-side only: it first renders once a journey step
+  arrives, then stays mounted for the rest of the session (no flicker while
+  steps load, switch journeys, or redirect on completion).
+
+  PROPS
+  ─────
+  The wrapper receives exactly one prop:
+
+    journeyName: string
+      Name of the journey currently driving the page (e.g. "Login",
+      "Register"). `''` means the AM default journey — the one the tenant
+      serves when the URL names no journey. Show your default-journey view
+      in that case; the header always renders something.
+
+  The framework passes no other props. Do not add required props of your own —
+  they will arrive undefined. Anything you need beyond `journeyName`, derive
+  inside this component from the framework exports.
+-->
+
+<script lang="ts">
+  // ─── Framework imports ──────────────────────────────────────────────────────
+  /**
+   * Import everything you need from '$login-framework' — the
+   * framework's centralized exports for custom components. No need to reach
+   * into internal aliases like $core, $components, or $journey directly.
+   *
+   * Available exports (see experimental/custom/login-framework.ts for the full list).
+   */
+  import type { CustomWrapperProps } from '$login-framework';
+
+  /** The one prop the framework passes: the active journey name (`''` = default). */
+  export let journeyName: CustomWrapperProps['journeyName'] = '';
+</script>
+
+<!--
+  Default markup: neutral no-op placeholder. Replace it with your own branding.
+
+  Example — branch the markup on the prop value. Render a "Register" banner
+  when journeyName is "Register", a default-journey banner when it is the
+  empty string (that is the AM default journey, the case where the URL named
+  no journey), and a journeyName-driven banner otherwise. In Svelte that is
+  an if/else if/else chain on journeyName.
+
+  All Tailwind classes use the framework's tw_ prefix so theme compilation
+  picks them up (see themes/default/config.cjs — prefix: 'tw_').
+-->
+<header class="tw_hidden"></header>
+
+<!--
+  Scoped styles for this wrapper. They apply only here — they won't leak to the
+  rest of the widget.
+-->
+<style>
+  /* Add your custom header styles here. */
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgerock/login-framework-cli",
-  "version": "0.0.0-beta-20261013223421",
+  "version": "0.0.0-beta-20261021173425",
   "description": "CLI tool for scaffolding and managing Ping Login Widget and Login App custom component projects",
   "type": "module",
   "exports": {
@@ -44,10 +44,10 @@
     "@effect/printer-ansi": "^0.49.0",
     "@effect/typeclass": "^0.40.0",
     "effect": "^3.21.0",
-    "svelte": "^5.55.7",
     "tar": "^7.5.21"
   },
   "devDependencies": {
+    "@effect/vitest": "0.29.0",
     "typescript": "^5.2.2",
     "vitest": "^3.2.6"
   },

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

@@ -1,29 +0,0 @@
-import { FileSystem, Path } from '@effect/platform';
-import { Effect } from 'effect';
-import { RegistryScanError } from '../errors.js';
-type ComponentType = 'stage' | 'callback';
-interface ComponentEntry {
-    filePath: string;
-    name: string;
-    type: ComponentType;
-    acceptedProps: string[];
-}
-/** Extracts names of all `export let` prop declarations from a Svelte component's instance script. */
-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>;
-export declare function buildRegistryContent(path: Path.Path, registryDir: string, stageComponents: ComponentEntry[], callbackComponents: ComponentEntry[]): string;
-/**
- * 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

@@ -1,176 +0,0 @@
-import { FileSystem, Path } from '@effect/platform';
-import { Console, Effect } from 'effect';
-import { parse } from 'svelte/compiler';
-import { RegistryScanError } from '../errors.js';
-// --------------------------------------------------------------------------
-// Helpers (exported for testing)
-// --------------------------------------------------------------------------
-/** Extracts names of all `export let` prop declarations from a Svelte component's instance script. */
-export function parseAcceptedProps(content) {
-    const abstractSyntaxTree = parse(content, { modern: false });
-    const props = [];
-    for (const node of abstractSyntaxTree.instance?.content.body ?? []) {
-        if (node.type !== 'ExportNamedDeclaration') {
-            continue;
-        }
-        if (node.declaration?.type === 'VariableDeclaration' && node.declaration.kind === 'let') {
-            for (const declarator of node.declaration.declarations) {
-                if (declarator.id.type === 'Identifier') {
-                    props.push(declarator.id.name);
-                }
-            }
-        }
-    }
-    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)
-// --------------------------------------------------------------------------
-export 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)}: { get component() { return ${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)}: { get component() { return ${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(', ')}`);
-    }
-});