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

package/dist/services/release.js

@@ -0,0 +1,86 @@
+import { Context, Effect, Layer, Schema } from 'effect';
+import { FileSystem, HttpClient, HttpClientResponse } from '@effect/platform';
+import { NodeHttpClient } from '@effect/platform-node';
+import { extract } from 'tar';
+import { InvalidVersionError, ReleaseFsError, ReleaseNetworkError, ReleaseNotFoundError, ReleaseParseError, } from '../errors.js';
+const REPO = 'ForgeRock/forgerock-web-login-framework';
+const API_HEADERS = {
+    'User-Agent': 'ping-lf-cli',
+    Accept: 'application/vnd.github.v3+json',
+};
+const VERSION_REGEX = /^v?\d+\.\d+\.\d+(-[\w.]+)?$/;
+const toCauseString = (cause) => cause instanceof Error ? cause.message : String(cause);
+export function validateVersion(version) {
+    return VERSION_REGEX.test(version)
+        ? Effect.succeed(version)
+        : Effect.fail(new InvalidVersionError({ version }));
+}
+const GithubReleaseSchema = Schema.Struct({
+    tag_name: Schema.String,
+    published_at: Schema.String,
+    draft: Schema.Boolean,
+    prerelease: Schema.Boolean,
+});
+const decodeGithubReleases = Schema.decodeUnknown(Schema.parseJson(Schema.Array(GithubReleaseSchema)));
+/**
+ * Parses a GitHub releases API JSON response and returns an array of
+ * `{ tag, publishedAt }` objects, excluding drafts and pre-releases.
+ */
+export function parseReleaseTags(json) {
+    return decodeGithubReleases(json).pipe(Effect.map((releases) => releases
+        .filter((r) => !r.draft && !r.prerelease)
+        .map((r) => ({ tag: r.tag_name, publishedAt: r.published_at.slice(0, 10) }))), Effect.mapError((cause) => new ReleaseParseError({ cause: toCauseString(cause) })));
+}
+export class Release extends Context.Tag('Release')() {
+}
+const LatestReleaseSchema = Schema.Struct({ tag_name: Schema.String });
+const decodeLatestRelease = Schema.decodeUnknown(Schema.parseJson(LatestReleaseSchema));
+const downloadAndExtract = (http, url, targetDir) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const tempDir = `${targetDir}/.framework-tmp`;
+    const tarPath = `${tempDir}/release.tar.gz`;
+    return yield* Effect.acquireRelease(Effect.gen(function* () {
+        yield* fs.makeDirectory(tempDir, { recursive: true }).pipe(Effect.mapError((cause) => new ReleaseFsError({
+            operation: 'makeDirectory',
+            cause: toCauseString(cause),
+        })));
+        const buffer = yield* HttpClient.followRedirects(http)
+            .get(url, { headers: { 'User-Agent': 'ping-lf-cli' } })
+            .pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.flatMap((res) => res.arrayBuffer), Effect.mapError((cause) => new ReleaseNetworkError({ cause: toCauseString(cause) })));
+        yield* fs
+            .writeFile(tarPath, new Uint8Array(buffer))
+            .pipe(Effect.mapError((cause) => new ReleaseFsError({ operation: 'writeFile', cause: toCauseString(cause) })));
+        yield* Effect.tryPromise({
+            try: () => extract({ file: tarPath, cwd: tempDir, strip: 1 }),
+            catch: (cause) => new ReleaseParseError({ cause: toCauseString(cause) }),
+        });
+        return tempDir;
+    }), (dir) => fs.remove(dir, { recursive: true }).pipe(Effect.ignore));
+});
+const buildGithubReleaseLayer = Layer.effect(Release, Effect.gen(function* () {
+    const http = yield* HttpClient.HttpClient;
+    return {
+        archiveUrl: (version) => `https://github.com/${REPO}/archive/refs/tags/${version}.tar.gz`,
+        resolveLatest: () => http
+            .get(`https://api.github.com/repos/${REPO}/releases/latest`, { headers: API_HEADERS })
+            .pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.flatMap((res) => res.text), Effect.mapError((cause) => new ReleaseNetworkError({ cause: toCauseString(cause) })), Effect.flatMap((text) => decodeLatestRelease(text).pipe(Effect.mapError((cause) => new ReleaseParseError({ cause: toCauseString(cause) })))), Effect.map((data) => data.tag_name)),
+        listReleases: () => http
+            .get(`https://api.github.com/repos/${REPO}/releases?per_page=20`, {
+            headers: API_HEADERS,
+        })
+            .pipe(Effect.flatMap(HttpClientResponse.filterStatusOk), Effect.flatMap((res) => res.text), Effect.mapError((cause) => new ReleaseNetworkError({ cause: toCauseString(cause) })), Effect.flatMap((json) => parseReleaseTags(json)), Effect.flatMap((releases) => releases.length === 0
+            ? Effect.fail(new ReleaseNotFoundError({ cause: 'No releases found on GitHub' }))
+            : Effect.succeed(releases))),
+        fetch: (version, targetDir) => Effect.gen(function* () {
+            yield* validateVersion(version);
+            const url = `https://github.com/${REPO}/archive/refs/tags/${version}.tar.gz`;
+            return yield* downloadAndExtract(http, url, targetDir);
+        }),
+        fetchBranch: (branch, targetDir) => {
+            const url = `https://github.com/${REPO}/archive/refs/heads/${branch}.tar.gz`;
+            return downloadAndExtract(http, url, targetDir);
+        },
+    };
+}));
+export const makeGithubReleaseLayer = (httpLayer) => buildGithubReleaseLayer.pipe(Layer.provide(httpLayer));
+export const GithubReleaseLayer = makeGithubReleaseLayer(NodeHttpClient.layer);

package/dist/templates/callback/__COMPONENT_SLUG__.svelte

@@ -0,0 +1,73 @@
+<!--
+@component
+Type: callback
+Name: __COMPONENT_NAME__
+
+Custom callback component. Replace this description with your own.
+-->
+
+<script lang="ts">
+  import type { FRCallback } from '@forgerock/javascript-sdk';
+  import type { z } from 'zod';
+
+  import type {
+    CallbackMetadata,
+    SelfSubmitFunction,
+    StepMetadata,
+  } from '$journey/journey.interfaces';
+  import type { styleSchema } from '$core/style.store';
+  import type { Maybe } from '$core/interfaces';
+
+  /**
+   * The AM callback instance for this component. Use `callback.getInputValue()`
+   * and `callback.setInputValue()` to read/write values sent back to the server.
+   */
+  export let callback: FRCallback;
+
+  /**
+   * Optional function to trigger self-submission (e.g. after an async action).
+   * Set to `null` when the callback does not need to submit the form itself.
+   */
+  export const selfSubmitFunction: Maybe<SelfSubmitFunction> = null;
+
+  /**
+   * Metadata about the current step (page node) — includes stage name,
+   * header/description overrides, and derived helpers like `isStepSelfSubmittable()`.
+   */
+  export const stepMetadata: Maybe<StepMetadata> = null;
+
+  /**
+   * Per-callback metadata from the step — may include policies, failed policies,
+   * and other AM-provided hints for rendering.
+   */
+  export const callbackMetadata: Maybe<CallbackMetadata> = null;
+
+  /**
+   * The widget's resolved style configuration (colors, logos, labels, etc.).
+   * Use this to keep your custom callback visually consistent with the theme.
+   */
+  export const style: z.infer<typeof styleSchema> = {};
+
+  // Suppress the "unused export" warning — remove `void` once you use `callback`.
+  void callback;
+</script>
+
+<!-- Replace the markup below with your custom callback UI. -->
+<div class="__COMPONENT_SLUG__ tw_p-4 tw_rounded-lg tw_border tw_border-secondary-light dark:tw_border-secondary-dark">
+  <p class="tw_text-base tw_text-secondary-dark dark:tw_text-secondary-light">
+    __COMPONENT_NAME__ callback — replace this with your implementation.
+  </p>
+</div>
+
+<!--
+  Scoped styles for this callback.
+  These styles only apply to this component — they won't leak to the rest of the widget.
+  You can also use Tailwind utility classes (prefixed with `tw_`) in the markup above.
+-->
+<style>
+  .__COMPONENT_SLUG__ {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+</style>

package/dist/templates/callback/__COMPONENT_SLUG__.utilities.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+
+import { format__COMPONENT_NAME__Label } from './__COMPONENT_SLUG__.utilities';
+
+describe('__COMPONENT_NAME__ utilities', () => {
+  it('trims whitespace from label', () => {
+    expect(format__COMPONENT_NAME__Label('  hello  ')).toBe('hello');
+  });
+});

package/dist/templates/callback/__COMPONENT_SLUG__.utilities.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for the __COMPONENT_NAME__ callback.
+ *
+ * Keep callback-specific helpers here — data formatting, validation, API calls, etc.
+ * This file is unit-tested independently of the Svelte component.
+ */
+
+/**
+ * Example utility — replace with your own helpers.
+ */
+export function format__COMPONENT_NAME__Label(value: string): string {
+  return value.trim();
+}

package/dist/templates/stage/__COMPONENT_SLUG__.svelte

@@ -0,0 +1,148 @@
+<!--
+@component
+Type: stage
+Name: __COMPONENT_NAME__
+
+Custom stage component. Replace this description with your own.
+
+A stage controls the layout and submission behaviour of an entire authentication
+step (page node). It receives the full FRStep, maps each callback to its
+component via CallbackMapper, and renders the form chrome (header, alerts,
+submit button, links).
+-->
+
+<script lang="ts">
+  import type { FRStep } from '@forgerock/javascript-sdk';
+  import { afterUpdate, onDestroy, onMount } from 'svelte';
+  import { get } from 'svelte/store';
+  import type { z } from 'zod';
+
+  import { interpolate } from '$core/_utilities/i18n.utilities';
+  import T from '$components/_utilities/locale-strings.svelte';
+  import Alert from '$components/primitives/alert/alert.svelte';
+  import Button from '$components/primitives/button/button.svelte';
+  import Form from '$components/primitives/form/form.svelte';
+  import { convertStringToKey } from '$journey/stages/_utilities/step.utilities';
+  import { captureLinks } from '$journey/stages/_utilities/stage.utilities';
+  import { styleStore } from '$core/style.store';
+  import type { styleSchema } from '$core/style.store';
+  import CallbackMapper from '$journey/_utilities/callback-mapper.svelte';
+
+  import type {
+    CallbackMetadata,
+    StageFormObject,
+    StageJourneyObject,
+    StepMetadata,
+  } from '$journey/journey.interfaces';
+  import type { Maybe } from '$core/interfaces';
+
+  /** Display mode — determines which chrome is visible (header, links, etc.). */
+  export let componentStyle: 'app' | 'inline' | 'modal';
+
+  /** Form helpers — `form.submit()` triggers the journey's next step. */
+  export let form: StageFormObject;
+
+  /** Bound to the underlying <form> element for programmatic access. */
+  export let formEl: HTMLFormElement | null = null;
+
+  /** Journey-level state — includes `loading` flag and navigation helpers. */
+  export let journey: StageJourneyObject;
+
+  /** Step + callback metadata from AM — policies, derived helpers, stage header. */
+  export let metadata: Maybe<{ callbacks: CallbackMetadata[]; step: StepMetadata }>;
+
+  /** The raw FRStep from the JavaScript SDK — contains all callbacks for this step. */
+  export let step: FRStep;
+
+  // Subscribe to style store so the template can pass styles to child callbacks.
+  let currentStyle: z.infer<typeof styleSchema> = get(styleStore);
+  const unsubStyle = styleStore.subscribe((v) => (currentStyle = v));
+  onDestroy(unsubStyle);
+
+  let alertNeedsFocus = false;
+  let formMessageKey = '';
+  let linkWrapper: HTMLElement;
+
+  /**
+   * Auto-submits the form when the step declares itself self-submittable
+   * (e.g. a DeviceProfile or PollingWait callback that needs no user input).
+   */
+  function determineSubmission() {
+    if (metadata?.step?.derived.isStepSelfSubmittable()) {
+      form?.submit();
+    }
+  }
+
+  afterUpdate(() => {
+    alertNeedsFocus = !!form?.message;
+  });
+
+  onMount(() => {
+    // In modal mode, intercept anchor clicks to navigate within the journey
+    // instead of performing a full page navigation.
+    if (componentStyle === 'modal') {
+      captureLinks(linkWrapper, journey);
+    }
+  });
+
+  $: {
+    formMessageKey = convertStringToKey(form?.message);
+  }
+</script>
+
+<!--
+  Replace or extend the markup below to customise the stage layout.
+  The key pieces to keep:
+    1. <Form> wrapper with `onSubmitWhenValid` bound to `form.submit`
+    2. The {#each} block that maps callbacks via <CallbackMapper>
+    3. A submit <Button> (unless the step is fully self-submittable)
+-->
+<Form bind:formEl ariaDescribedBy="__COMPONENT_SLUG__FailureAlert" onSubmitWhenValid={form?.submit}>
+  {#if componentStyle !== 'inline'}
+    <h1 class="tw_primary-header dark:tw_primary-header_dark">
+      <T key="loginHeader" />
+    </h1>
+  {/if}
+
+  {#if form?.message}
+    <Alert id="__COMPONENT_SLUG__FailureAlert" needsFocus={alertNeedsFocus} type="error">
+      {interpolate(formMessageKey, null, form?.message)}
+    </Alert>
+  {/if}
+
+  {#each step?.callbacks as callback, idx}
+    <CallbackMapper
+      props={{
+        callback,
+        callbackMetadata: metadata?.callbacks[idx],
+        selfSubmitFunction: determineSubmission,
+        stepMetadata: metadata?.step && { ...metadata.step },
+        style: currentStyle,
+      }}
+    />
+  {/each}
+
+  {#if metadata?.step?.derived.isUserInputOptional || !metadata?.step?.derived.isStepSelfSubmittable()}
+    <Button busy={journey?.loading} style="primary" type="submit" width="full">
+      <T key="loginButton" />
+    </Button>
+  {/if}
+
+  {#if componentStyle !== 'inline'}
+    <p
+      bind:this={linkWrapper}
+      class="tw_text-base tw_text-center tw_py-4 tw_text-secondary-dark dark:tw_text-secondary-light"
+    >
+      <T key="dontHaveAnAccount" html={true} />
+    </p>
+  {/if}
+</Form>
+
+<!--
+  Scoped styles for this stage.
+  These styles only apply to this component — they won't leak to the rest of the widget.
+  You can also use Tailwind utility classes (prefixed with `tw_`) in the markup above.
+-->
+<style>
+  /* Add your custom stage styles here. */
+</style>

package/dist/templates/stage/__COMPONENT_SLUG__.utilities.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+
+import { format__COMPONENT_NAME__Label } from './__COMPONENT_SLUG__.utilities';
+
+describe('__COMPONENT_NAME__ utilities', () => {
+  it('trims whitespace from label', () => {
+    expect(format__COMPONENT_NAME__Label('  hello  ')).toBe('hello');
+  });
+});

package/dist/templates/stage/__COMPONENT_SLUG__.utilities.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for the __COMPONENT_NAME__ stage.
+ *
+ * Keep stage-specific helpers here — data formatting, validation, API calls, etc.
+ * This file is unit-tested independently of the Svelte component.
+ */
+
+/**
+ * Example utility — replace with your own helpers.
+ */
+export function format__COMPONENT_NAME__Label(value: string): string {
+  return value.trim();
+}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+/** Converts all backslashes to forward slashes for cross-platform path comparisons. */
+export declare function normalizeSeparators(p: string): string;

package/dist/utils.js

@@ -0,0 +1,4 @@
+/** Converts all backslashes to forward slashes for cross-platform path comparisons. */
+export function normalizeSeparators(p) {
+    return p.replace(/\\/g, '/');
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forgerock/login-framework-cli",
+  "version": "0.0.0-beta.0",
+  "description": "CLI tool for scaffolding and managing Ping Login Widget and Login App custom component projects",
+  "type": "module",
+  "exports": "./dist/main.js",
+  "main": "./dist/main.js",
+  "module": "./dist/main.js",
+  "bin": {
+    "ping-lf": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "keywords": [
+    "ping-identity",
+    "forgerock",
+    "login",
+    "widget",
+    "cli",
+    "generator",
+    "svelte"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ForgeRock/forgerock-web-login-framework.git",
+    "directory": "tools/cli"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/cli": "^0.75.0",
+    "@effect/platform": "^0.96.0",
+    "@effect/platform-node": "^0.106.0",
+    "@effect/printer": "^0.49.0",
+    "@effect/printer-ansi": "^0.49.0",
+    "@effect/typeclass": "^0.40.0",
+    "effect": "^3.21.0",
+    "tar": "^7.5.13"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.2",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/main.js && ([ -d templates ] && cp -r templates/ dist/templates/ || true)",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/scripts/generate-registry.mjs

@@ -0,0 +1,23 @@
+#!/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 @ping-identity/login-framework-cli run build
+ */
+import { Effect } from 'effect';
+import { NodeContext, NodeRuntime } from '@effect/platform-node';
+
+const { runRegistryScript } = await import('../dist/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)));