@pwfabric/cli 0.0.0-stage → 1.0.0-rc.1

package/dist/commands/lib/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../../src/commands/lib/project.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The project folder as the commands see it: which files belong to the pack,\n * where the local pack cache lives, and how a pack source (folder or archive)\n * is opened.\n *\n * A project is a pwpack folder plus things that are never packed: the `.pwf/`\n * cache (installed pack builds), the `.gitignore` next to it, and anything\n * else outside the pack content (`packContent`: `pwpack.json`, `LICENSE`,\n * `NOTICE`, `README.md`, `app/`, `atoms/`, `media/`).\n */\nimport { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'\nimport { dirname, join, resolve } from 'node:path'\nimport {\n  DEFAULT_IGNORED_NAMES,\n  isSafePackPath,\n  readFolder,\n  readPwpack,\n  type PackFolder,\n} from '@pwfabric/pack'\n\n/** The project-local working directory (pack cache, build output of other commands). */\nexport const PWF_DIR = '.pwf'\n/** Installed pack builds, one folder per `<id>@<version>`. */\nexport const PACK_CACHE_DIR = `${PWF_DIR}/packs`\n/** The note `create` writes into `atoms/`. Pack content (documentation, `DOC_FILE`), so it travels with the pack. */\nexport const ATOMS_README = 'atoms/README.md'\n\n/** Names skipped at any depth when a project is read: the defaults plus the cache and VCS ignore file. */\nexport const PROJECT_IGNORED_NAMES: ReadonlySet<string> = new Set([...DEFAULT_IGNORED_NAMES, PWF_DIR, '.gitignore'])\n\n/**\n * Reads a project folder into memory, without the cache. The author's tooling\n * (`package.json`, `scripts/`, …) is still in it — validation reports on it;\n * `packContent` is what is packed, installed and hashed.\n */\nexport async function readProject(dir: string): Promise<PackFolder> {\n  const read = await readFolder(dir, { ignore: PROJECT_IGNORED_NAMES })\n  // A dot entry at the root (`.editorconfig`, `.vscode/`, …) is never pack\n  // content; it is the author's environment and is not reported on.\n  return { files: new Map([...read.files].filter(([path]) => !path.startsWith('.'))) }\n}\n\n/**\n * Opens a pack source: a folder (read like a project, so its own `.pwf/`\n * cache never travels) or a `.pwpack` / `.tgz` archive.\n */\nexport async function readPackSource(path: string): Promise<PackFolder> {\n  const st = await stat(path).catch(() => null)\n  if (!st) throw new Error(`no such file or folder: ${path}`)\n  if (st.isDirectory()) return readProject(path)\n  return readPwpack(new Uint8Array(await readFile(path)))\n}\n\n/**\n * Relative folder of one pack build in the cache: `.pwf/packs/<id>@<version>`.\n * A scoped id (`@pwpack/acme/cards`) nests the way npm scopes do. Throws when\n * the id or version could escape the cache.\n */\nexport function cacheRelDir(id: string, version: string): string {\n  const rel = `${id}@${version}`\n  if (!isSafePackPath(rel) || /[<>:\"|?*]/.test(rel)) throw new Error(`pack id \"${id}\" with version \"${version}\" is not usable as a cache folder name`)\n  return `${PACK_CACHE_DIR}/${rel}`\n}\n\n/** Absolute folder of one pack build in a project's cache. */\nexport function cacheDir(root: string, id: string, version: string): string {\n  return join(root, ...cacheRelDir(id, version).split('/'))\n}\n\n/** Reads a cached pack build exactly as it was written: nothing is skipped. */\nexport async function readCachedPack(dir: string): Promise<PackFolder> {\n  return readFolder(dir, { ignore: new Set() })\n}\n\n/** Writes a pack folder to disk, replacing whatever was there. */\nexport async function writePackFolder(dir: string, pack: PackFolder): Promise<void> {\n  await rm(dir, { recursive: true, force: true })\n  await mkdir(dir, { recursive: true })\n  for (const [path, bytes] of pack.files) {\n    const target = join(dir, ...path.split('/'))\n    await mkdir(dirname(target), { recursive: true })\n    await writeFile(target, bytes)\n  }\n}\n\n/** Resolves a user-given path against the command's working directory. */\nexport function resolveFrom(cwd: string, path: string | undefined): string {\n  return resolve(cwd, path ?? '.')\n}\n"]}

package/dist/commands/lib/report.d.ts

@@ -0,0 +1,15 @@
+import { type PackFolder, type PackIssue, type PackValidation } from '@pwfabric/pack';
+import type { CommandIO } from '../types.js';
+/**
+ * Checks every `packs[]` pin against `.pwf/packs/<id>@<version>/`.
+ * A build that is not cached is a warning (`PIN_NOT_CACHED`: `pwf add` it);
+ * a cached build whose content hash differs from the pin is an error
+ * (`PIN_HASH_MISMATCH`).
+ */
+export declare function checkPins(root: string, identity: PackValidation['identity']): Promise<PackIssue[]>;
+/** `validatePack` plus {@link checkPins}, as one result. */
+export declare function validateProject(root: string, pack: PackFolder): Promise<PackValidation>;
+/** Prints issues grouped by severity, errors first. Prints nothing for an empty list. */
+export declare function printIssues(io: CommandIO, issues: readonly PackIssue[]): void;
+/** `n errors, n warnings` for a summary line. */
+export declare function countLine(issues: readonly PackIssue[]): string;

package/dist/commands/lib/report.js

@@ -0,0 +1,75 @@
+/**
+ * Validation as the commands report it: the pack library's findings plus
+ * the project's pins checked against its local cache.
+ */
+import { existsSync } from 'node:fs';
+import { hashPack, validatePack } from '@pwfabric/pack';
+import { cacheDir, cacheRelDir, readCachedPack } from './project.js';
+import { pinsOf } from './identity.js';
+/**
+ * Checks every `packs[]` pin against `.pwf/packs/<id>@<version>/`.
+ * A build that is not cached is a warning (`PIN_NOT_CACHED`: `pwf add` it);
+ * a cached build whose content hash differs from the pin is an error
+ * (`PIN_HASH_MISMATCH`).
+ */
+export async function checkPins(root, identity) {
+    const issues = [];
+    for (const pin of pinsOf(identity)) {
+        let dir;
+        try {
+            dir = cacheDir(root, pin.id, pin.version);
+        }
+        catch (e) {
+            issues.push({ severity: 'error', code: 'PIN_INVALID', path: 'pwpack.json', message: e.message });
+            continue;
+        }
+        const rel = cacheRelDir(pin.id, pin.version);
+        if (!existsSync(dir)) {
+            issues.push({
+                severity: 'warning',
+                code: 'PIN_NOT_CACHED',
+                path: rel,
+                message: `${pin.id}@${pin.version} is pinned but not in ${rel}; run \`pwf add <its .pwpack or folder>\``,
+            });
+            continue;
+        }
+        const actual = hashPack(await readCachedPack(dir));
+        if (actual !== pin.hash) {
+            issues.push({
+                severity: 'error',
+                code: 'PIN_HASH_MISMATCH',
+                path: rel,
+                message: `${pin.id}@${pin.version} is pinned at ${pin.hash} but the cached build hashes ${actual}`,
+            });
+        }
+    }
+    return issues;
+}
+/** `validatePack` plus {@link checkPins}, as one result. */
+export async function validateProject(root, pack) {
+    const result = validatePack(pack);
+    const pinIssues = await checkPins(root, result.identity);
+    const issues = [...result.issues, ...pinIssues];
+    return { ...result, issues, ok: !issues.some((i) => i.severity === 'error') };
+}
+const SEVERITIES = ['error', 'warning', 'info'];
+const HEADINGS = { error: 'Errors', warning: 'Warnings', info: 'Notes' };
+/** Prints issues grouped by severity, errors first. Prints nothing for an empty list. */
+export function printIssues(io, issues) {
+    for (const severity of SEVERITIES) {
+        const group = issues.filter((i) => i.severity === severity);
+        if (group.length === 0)
+            continue;
+        const write = severity === 'error' ? io.err.bind(io) : io.out.bind(io);
+        write(`${HEADINGS[severity]} (${group.length}):`);
+        for (const issue of group)
+            write(`  ${issue.code}${issue.path ? ` ${issue.path}` : ''}: ${issue.message}`);
+    }
+}
+/** `n errors, n warnings` for a summary line. */
+export function countLine(issues) {
+    const n = (s) => issues.filter((i) => i.severity === s).length;
+    const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+    return `${plural(n('error'), 'error')}, ${plural(n('warning'), 'warning')}`;
+}
+//# sourceMappingURL=report.js.map

package/dist/commands/lib/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/lib/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validation as the commands report it: the pack library's findings plus\n * the project's pins checked against its local cache.\n */\nimport { existsSync } from 'node:fs'\nimport { hashPack, validatePack, type PackFolder, type PackIssue, type PackValidation } from '@pwfabric/pack'\nimport type { CommandIO } from '../types.js'\nimport { cacheDir, cacheRelDir, readCachedPack } from './project.js'\nimport { pinsOf } from './identity.js'\n\n/**\n * Checks every `packs[]` pin against `.pwf/packs/<id>@<version>/`.\n * A build that is not cached is a warning (`PIN_NOT_CACHED`: `pwf add` it);\n * a cached build whose content hash differs from the pin is an error\n * (`PIN_HASH_MISMATCH`).\n */\nexport async function checkPins(root: string, identity: PackValidation['identity']): Promise<PackIssue[]> {\n  const issues: PackIssue[] = []\n  for (const pin of pinsOf(identity)) {\n    let dir: string\n    try {\n      dir = cacheDir(root, pin.id, pin.version)\n    } catch (e) {\n      issues.push({ severity: 'error', code: 'PIN_INVALID', path: 'pwpack.json', message: (e as Error).message })\n      continue\n    }\n    const rel = cacheRelDir(pin.id, pin.version)\n    if (!existsSync(dir)) {\n      issues.push({\n        severity: 'warning',\n        code: 'PIN_NOT_CACHED',\n        path: rel,\n        message: `${pin.id}@${pin.version} is pinned but not in ${rel}; run \\`pwf add <its .pwpack or folder>\\``,\n      })\n      continue\n    }\n    const actual = hashPack(await readCachedPack(dir))\n    if (actual !== pin.hash) {\n      issues.push({\n        severity: 'error',\n        code: 'PIN_HASH_MISMATCH',\n        path: rel,\n        message: `${pin.id}@${pin.version} is pinned at ${pin.hash} but the cached build hashes ${actual}`,\n      })\n    }\n  }\n  return issues\n}\n\n/** `validatePack` plus {@link checkPins}, as one result. */\nexport async function validateProject(root: string, pack: PackFolder): Promise<PackValidation> {\n  const result = validatePack(pack)\n  const pinIssues = await checkPins(root, result.identity)\n  const issues = [...result.issues, ...pinIssues]\n  return { ...result, issues, ok: !issues.some((i) => i.severity === 'error') }\n}\n\nconst SEVERITIES = ['error', 'warning', 'info'] as const\nconst HEADINGS = { error: 'Errors', warning: 'Warnings', info: 'Notes' } as const\n\n/** Prints issues grouped by severity, errors first. Prints nothing for an empty list. */\nexport function printIssues(io: CommandIO, issues: readonly PackIssue[]): void {\n  for (const severity of SEVERITIES) {\n    const group = issues.filter((i) => i.severity === severity)\n    if (group.length === 0) continue\n    const write = severity === 'error' ? io.err.bind(io) : io.out.bind(io)\n    write(`${HEADINGS[severity]} (${group.length}):`)\n    for (const issue of group) write(`  ${issue.code}${issue.path ? ` ${issue.path}` : ''}: ${issue.message}`)\n  }\n}\n\n/** `n errors, n warnings` for a summary line. */\nexport function countLine(issues: readonly PackIssue[]): string {\n  const n = (s: PackIssue['severity']): number => issues.filter((i) => i.severity === s).length\n  const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`\n  return `${plural(n('error'), 'error')}, ${plural(n('warning'), 'warning')}`\n}\n"]}

package/dist/commands/lib/starter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What `pwf create` writes: the starter app's documents, composed only from
+ * the block types and themes the foundation pack actually carries.
+ */
+import type { PackFolder, PackValidation } from '@pwfabric/pack';
+export interface FoundationBlock {
+    /** Block type a receipt names (the manifest's `name`). */
+    readonly type: string;
+    /** Atom id, `<category>.<name>`. */
+    readonly id: string;
+    /** Prop names the manifest declares. */
+    readonly props: readonly string[];
+}
+export interface FoundationCatalog {
+    readonly blocks: readonly FoundationBlock[];
+    /** Theme ids (`ui-appearance` atoms). */
+    readonly themes: readonly string[];
+}
+/**
+ * Block types and themes of a pack, from its derived atoms. A block's type is
+ * the `name` of the `manifest.json` next to its component (falling back to the
+ * last segment of its id); its props are the manifest's `definition.props`.
+ */
+export declare function catalogOf(pack: PackFolder, validation: PackValidation): FoundationCatalog;
+export interface BlockNode {
+    readonly id: string;
+    readonly type: string;
+    readonly props: Record<string, unknown>;
+}
+/** Starter blocks for the home page, using only block types the catalog has. */
+export declare function starterBlocks(catalog: FoundationCatalog, title: string): BlockNode[];
+/** The theme the starter uses: `theme-zinc` when present (a neutral default), otherwise the first by id. */
+export declare function starterTheme(catalog: FoundationCatalog): string | undefined;
+/** `my-shop` → `My Shop`. */
+export declare function titleOf(name: string): string;
+export declare function starterPlan(name: string, title: string, blocks: readonly BlockNode[], foundationId: string, theme: string | undefined): unknown;
+export declare function starterAppearance(theme: string | undefined): unknown;
+export declare function starterNavigation(): unknown;
+export declare function starterReceipt(blocks: readonly BlockNode[]): unknown;
+export declare const ATOMS_README_TEXT = "# atoms/\n\nThis app's own reusable parts. Empty to start: the app is composed from the\nfoundation pack pinned in `pwpack.json`.\n\nAdd a block as `atoms/blocks/<category>/<name>/component.tsx` with a\n`manifest.json` next to it; see the pwpack format and block manifest\ndocuments of the PWFabric specification for every atom family.\n\nThis README is documentation, not an atom: it travels with the pack and\nvalidation notes it as such (DOC_FILE).\n";
+export declare const GITIGNORE_TEXT = ".pwf/\n*.pwpack\n";

package/dist/commands/lib/starter.js

@@ -0,0 +1,136 @@
+import { stripBom } from './identity.js';
+function parseObject(bytes) {
+    if (!bytes)
+        return null;
+    try {
+        const v = JSON.parse(stripBom(new TextDecoder().decode(bytes)));
+        return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Block types and themes of a pack, from its derived atoms. A block's type is
+ * the `name` of the `manifest.json` next to its component (falling back to the
+ * last segment of its id); its props are the manifest's `definition.props`.
+ */
+export function catalogOf(pack, validation) {
+    const blocks = [];
+    const themes = [];
+    for (const atom of validation.atoms) {
+        if (atom.kind === 'ui-appearance') {
+            const manifest = parseObject(pack.files.get(atom.relPath));
+            themes.push(typeof manifest?.id === 'string' ? manifest.id : atom.id);
+            continue;
+        }
+        if (atom.kind !== 'block')
+            continue;
+        const dir = atom.relPath.slice(0, atom.relPath.lastIndexOf('/') + 1);
+        const manifest = parseObject(pack.files.get(`${dir}manifest.json`));
+        const name = typeof manifest?.name === 'string' ? manifest.name : atom.id.split('.').pop();
+        const definition = manifest?.definition;
+        const props = Array.isArray(definition?.props)
+            ? definition.props.flatMap((p) => p !== null && typeof p === 'object' && typeof p.name === 'string' ? [p.name] : [])
+            : [];
+        blocks.push({ type: name, id: atom.id, props });
+    }
+    return { blocks, themes };
+}
+/** The starter page, in order: a heading, a paragraph and a button. */
+const SLOTS = [
+    { id: 'title', types: ['heading', 'title'], textProps: ['text', 'content', 'title', 'label'], text: (t) => t, extra: { level: 'h1' } },
+    {
+        id: 'intro',
+        types: ['text', 'paragraph', 'prose'],
+        textProps: ['content', 'text', 'body', 'markdown'],
+        text: () => 'Edit app/surfaces/home.receipt.json to change this page, then run pwf dev to see it.',
+        extra: {},
+    },
+    { id: 'cta', types: ['button'], textProps: ['label', 'text'], text: () => 'Get started', extra: { href: '/' } },
+];
+/** Starter blocks for the home page, using only block types the catalog has. */
+export function starterBlocks(catalog, title) {
+    const out = [];
+    for (const slot of SLOTS) {
+        const block = slot.types.map((t) => catalog.blocks.find((b) => b.type === t)).find((b) => b !== undefined);
+        if (!block)
+            continue;
+        const props = {};
+        const textProp = slot.textProps.find((p) => block.props.includes(p));
+        if (textProp)
+            props[textProp] = slot.text(title);
+        for (const [k, v] of Object.entries(slot.extra))
+            if (block.props.includes(k))
+                props[k] = v;
+        out.push({ id: slot.id, type: block.type, props });
+    }
+    return out;
+}
+/** The theme the starter uses: `theme-zinc` when present (a neutral default), otherwise the first by id. */
+export function starterTheme(catalog) {
+    if (catalog.themes.includes('theme-zinc'))
+        return 'theme-zinc';
+    return [...catalog.themes].sort()[0];
+}
+/** `my-shop` → `My Shop`. */
+export function titleOf(name) {
+    return name
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((w) => w[0]?.toUpperCase() + w.slice(1))
+        .join(' ');
+}
+export function starterPlan(name, title, blocks, foundationId, theme) {
+    return {
+        title: title.slice(0, 80),
+        intent: {
+            purpose: `${title}: describe what this app is for`,
+            audience: 'Describe who will use it',
+            tone: 'Clear and friendly',
+            successCriteria: 'The home page renders',
+        },
+        theme: { direction: 'Clean and neutral', paletteHint: theme ?? 'the foundation default', status: 'applied' },
+        capabilities: [],
+        media: [],
+        customBlocks: [],
+        surfaces: [
+            {
+                key: 'home',
+                name: 'Home',
+                isEntry: true,
+                purpose: `The first page of ${name}`,
+                keyContent: blocks.map((b) => b.id),
+                linksTo: [],
+                usesCapabilities: [],
+                usesMedia: [],
+                usesCustomBlocks: [],
+                status: 'applied',
+            },
+        ],
+        packs: [{ id: foundationId }],
+    };
+}
+export function starterAppearance(theme) {
+    return theme ? { use: theme } : { config: { mode: { policy: 'light' } } };
+}
+export function starterNavigation() {
+    return { navbar: { links: [{ label: 'Home', href: '/' }] } };
+}
+export function starterReceipt(blocks) {
+    return { title: 'Home', blocks };
+}
+export const ATOMS_README_TEXT = `# atoms/
+
+This app's own reusable parts. Empty to start: the app is composed from the
+foundation pack pinned in \`pwpack.json\`.
+
+Add a block as \`atoms/blocks/<category>/<name>/component.tsx\` with a
+\`manifest.json\` next to it; see the pwpack format and block manifest
+documents of the PWFabric specification for every atom family.
+
+This README is documentation, not an atom: it travels with the pack and
+validation notes it as such (DOC_FILE).
+`;
+export const GITIGNORE_TEXT = `.pwf/\n*.pwpack\n`;
+//# sourceMappingURL=starter.js.map

package/dist/commands/lib/starter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.js","sourceRoot":"","sources":["../../../src/commands/lib/starter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `pwf create` writes: the starter app's documents, composed only from\n * the block types and themes the foundation pack actually carries.\n */\nimport type { PackFolder, PackValidation } from '@pwfabric/pack'\nimport { stripBom } from './identity.js'\n\nexport interface FoundationBlock {\n  /** Block type a receipt names (the manifest's `name`). */\n  readonly type: string\n  /** Atom id, `<category>.<name>`. */\n  readonly id: string\n  /** Prop names the manifest declares. */\n  readonly props: readonly string[]\n}\n\nexport interface FoundationCatalog {\n  readonly blocks: readonly FoundationBlock[]\n  /** Theme ids (`ui-appearance` atoms). */\n  readonly themes: readonly string[]\n}\n\nfunction parseObject(bytes: Uint8Array | undefined): Record<string, unknown> | null {\n  if (!bytes) return null\n  try {\n    const v: unknown = JSON.parse(stripBom(new TextDecoder().decode(bytes)))\n    return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Block types and themes of a pack, from its derived atoms. A block's type is\n * the `name` of the `manifest.json` next to its component (falling back to the\n * last segment of its id); its props are the manifest's `definition.props`.\n */\nexport function catalogOf(pack: PackFolder, validation: PackValidation): FoundationCatalog {\n  const blocks: FoundationBlock[] = []\n  const themes: string[] = []\n  for (const atom of validation.atoms) {\n    if (atom.kind === 'ui-appearance') {\n      const manifest = parseObject(pack.files.get(atom.relPath))\n      themes.push(typeof manifest?.id === 'string' ? manifest.id : atom.id)\n      continue\n    }\n    if (atom.kind !== 'block') continue\n    const dir = atom.relPath.slice(0, atom.relPath.lastIndexOf('/') + 1)\n    const manifest = parseObject(pack.files.get(`${dir}manifest.json`))\n    const name = typeof manifest?.name === 'string' ? manifest.name : (atom.id.split('.').pop() as string)\n    const definition = manifest?.definition as { props?: unknown } | undefined\n    const props = Array.isArray(definition?.props)\n      ? (definition.props as unknown[]).flatMap((p) =>\n          p !== null && typeof p === 'object' && typeof (p as { name?: unknown }).name === 'string' ? [(p as { name: string }).name] : []\n        )\n      : []\n    blocks.push({ type: name, id: atom.id, props })\n  }\n  return { blocks, themes }\n}\n\ninterface Slot {\n  readonly id: string\n  readonly types: readonly string[]\n  readonly textProps: readonly string[]\n  readonly text: (title: string) => string\n  readonly extra: Readonly<Record<string, unknown>>\n}\n\n/** The starter page, in order: a heading, a paragraph and a button. */\nconst SLOTS: readonly Slot[] = [\n  { id: 'title', types: ['heading', 'title'], textProps: ['text', 'content', 'title', 'label'], text: (t) => t, extra: { level: 'h1' } },\n  {\n    id: 'intro',\n    types: ['text', 'paragraph', 'prose'],\n    textProps: ['content', 'text', 'body', 'markdown'],\n    text: () => 'Edit app/surfaces/home.receipt.json to change this page, then run pwf dev to see it.',\n    extra: {},\n  },\n  { id: 'cta', types: ['button'], textProps: ['label', 'text'], text: () => 'Get started', extra: { href: '/' } },\n]\n\nexport interface BlockNode {\n  readonly id: string\n  readonly type: string\n  readonly props: Record<string, unknown>\n}\n\n/** Starter blocks for the home page, using only block types the catalog has. */\nexport function starterBlocks(catalog: FoundationCatalog, title: string): BlockNode[] {\n  const out: BlockNode[] = []\n  for (const slot of SLOTS) {\n    const block = slot.types.map((t) => catalog.blocks.find((b) => b.type === t)).find((b) => b !== undefined)\n    if (!block) continue\n    const props: Record<string, unknown> = {}\n    const textProp = slot.textProps.find((p) => block.props.includes(p))\n    if (textProp) props[textProp] = slot.text(title)\n    for (const [k, v] of Object.entries(slot.extra)) if (block.props.includes(k)) props[k] = v\n    out.push({ id: slot.id, type: block.type, props })\n  }\n  return out\n}\n\n/** The theme the starter uses: `theme-zinc` when present (a neutral default), otherwise the first by id. */\nexport function starterTheme(catalog: FoundationCatalog): string | undefined {\n  if (catalog.themes.includes('theme-zinc')) return 'theme-zinc'\n  return [...catalog.themes].sort()[0]\n}\n\n/** `my-shop` → `My Shop`. */\nexport function titleOf(name: string): string {\n  return name\n    .split(/[-_]+/)\n    .filter(Boolean)\n    .map((w) => w[0]?.toUpperCase() + w.slice(1))\n    .join(' ')\n}\n\nexport function starterPlan(name: string, title: string, blocks: readonly BlockNode[], foundationId: string, theme: string | undefined): unknown {\n  return {\n    title: title.slice(0, 80),\n    intent: {\n      purpose: `${title}: describe what this app is for`,\n      audience: 'Describe who will use it',\n      tone: 'Clear and friendly',\n      successCriteria: 'The home page renders',\n    },\n    theme: { direction: 'Clean and neutral', paletteHint: theme ?? 'the foundation default', status: 'applied' },\n    capabilities: [],\n    media: [],\n    customBlocks: [],\n    surfaces: [\n      {\n        key: 'home',\n        name: 'Home',\n        isEntry: true,\n        purpose: `The first page of ${name}`,\n        keyContent: blocks.map((b) => b.id),\n        linksTo: [],\n        usesCapabilities: [],\n        usesMedia: [],\n        usesCustomBlocks: [],\n        status: 'applied',\n      },\n    ],\n    packs: [{ id: foundationId }],\n  }\n}\n\nexport function starterAppearance(theme: string | undefined): unknown {\n  return theme ? { use: theme } : { config: { mode: { policy: 'light' } } }\n}\n\nexport function starterNavigation(): unknown {\n  return { navbar: { links: [{ label: 'Home', href: '/' }] } }\n}\n\nexport function starterReceipt(blocks: readonly BlockNode[]): unknown {\n  return { title: 'Home', blocks }\n}\n\nexport const ATOMS_README_TEXT = `# atoms/\n\nThis app's own reusable parts. Empty to start: the app is composed from the\nfoundation pack pinned in \\`pwpack.json\\`.\n\nAdd a block as \\`atoms/blocks/<category>/<name>/component.tsx\\` with a\n\\`manifest.json\\` next to it; see the pwpack format and block manifest\ndocuments of the PWFabric specification for every atom family.\n\nThis README is documentation, not an atom: it travels with the pack and\nvalidation notes it as such (DOC_FILE).\n`\n\nexport const GITIGNORE_TEXT = `.pwf/\\n*.pwpack\\n`\n"]}

package/dist/commands/lib/static-server.d.ts

@@ -0,0 +1,45 @@
+export declare const CONTENT_TYPES: Readonly<Record<string, string>>;
+export declare function contentTypeOf(path: string): string;
+/** Where the files come from: a folder on disk, or files held in memory (an opened archive). */
+export type StaticSource = {
+    readonly dir: string;
+} | {
+    readonly files: ReadonlyMap<string, Uint8Array>;
+};
+export interface StaticServerOptions {
+    readonly source: StaticSource;
+    /** 0 picks a free port. */
+    readonly port: number;
+    /** Default 127.0.0.1. */
+    readonly hostname?: string;
+}
+export interface StaticServer {
+    readonly url: string;
+    readonly port: number;
+    close(): Promise<void>;
+}
+/** The request path as a safe relative POSIX path, or null when it is malformed or escapes the root. */
+export declare function requestPath(rawUrl: string): string | null;
+/** Resolves a request to a file: the path itself, `<path>/index.html`, then the SPA fallback for page paths. */
+export declare function resolveRequest(source: StaticSource, rel: string): Promise<{
+    path: string;
+    body: Uint8Array;
+} | null>;
+/** The static-host headers file a build writes beside `index.html`. */
+export declare const HEADERS_FILE = "_headers";
+/** One rule of a `_headers` file: a path pattern and the headers it adds. */
+export interface HeaderRule {
+    readonly pattern: string;
+    readonly headers: readonly (readonly [string, string])[];
+}
+/**
+ * Parses the `_headers` convention of static hosts: a line that starts at
+ * column 0 is a path pattern (`/*`, `/assets/*`, `/about`), the indented
+ * `Name: value` lines under it are the headers it adds. `#` lines are
+ * comments.
+ */
+export declare function parseHeadersFile(text: string): HeaderRule[];
+/** Whether a `_headers` pattern matches a request path (`/` + the relative path). */
+export declare function headerPatternMatches(pattern: string, path: string): boolean;
+/** Starts the server; resolves once it is listening. */
+export declare function startStaticServer(options: StaticServerOptions): Promise<StaticServer>;

package/dist/commands/lib/static-server.js

@@ -0,0 +1,176 @@
+/**
+ * A small static file server for a built pwapp: correct content types, no
+ * directory listings, no path escapes, and an SPA fallback to `index.html`
+ * for page paths.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, join, resolve, sep } from 'node:path';
+import { withBaseHref } from '../../dev/shell.js';
+export const CONTENT_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.map': 'application/json; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.wasm': 'application/wasm',
+};
+export function contentTypeOf(path) {
+    return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+/** The request path as a safe relative POSIX path, or null when it is malformed or escapes the root. */
+export function requestPath(rawUrl) {
+    let pathname;
+    try {
+        pathname = decodeURIComponent(new URL(rawUrl, 'http://localhost').pathname);
+    }
+    catch {
+        return null;
+    }
+    if (pathname.includes('\0') || pathname.includes('\\'))
+        return null;
+    const parts = [];
+    for (const seg of pathname.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            return null;
+        parts.push(seg);
+    }
+    return parts.join('/');
+}
+async function load(source, rel) {
+    if ('files' in source)
+        return source.files.get(rel) ?? null;
+    const root = resolve(source.dir);
+    const abs = resolve(join(root, ...rel.split('/')));
+    if (abs !== root && !abs.startsWith(root + sep))
+        return null;
+    const st = await stat(abs).catch(() => null);
+    if (!st?.isFile())
+        return null;
+    return new Uint8Array(await readFile(abs));
+}
+/** Resolves a request to a file: the path itself, `<path>/index.html`, then the SPA fallback for page paths. */
+export async function resolveRequest(source, rel) {
+    const candidates = rel === '' ? ['index.html'] : [rel, `${rel}/index.html`];
+    // A path whose last segment has no extension is a page path: answer it with the shell.
+    if (rel !== '' && extname(rel) === '')
+        candidates.push('index.html');
+    for (const path of candidates) {
+        const body = await load(source, path);
+        if (body)
+            return { path, body };
+    }
+    return null;
+}
+const TEXT = { 'content-type': 'text/plain; charset=utf-8' };
+/** The static-host headers file a build writes beside `index.html`. */
+export const HEADERS_FILE = '_headers';
+/**
+ * Parses the `_headers` convention of static hosts: a line that starts at
+ * column 0 is a path pattern (`/*`, `/assets/*`, `/about`), the indented
+ * `Name: value` lines under it are the headers it adds. `#` lines are
+ * comments.
+ */
+export function parseHeadersFile(text) {
+    const rules = [];
+    for (const raw of text.split(/\r?\n/)) {
+        if (!raw.trim() || raw.trim().startsWith('#'))
+            continue;
+        if (!/^\s/.test(raw)) {
+            rules.push({ pattern: raw.trim(), headers: [] });
+            continue;
+        }
+        const at = raw.indexOf(':');
+        const rule = rules[rules.length - 1];
+        if (at > 0 && rule)
+            rule.headers.push([raw.slice(0, at).trim(), raw.slice(at + 1).trim()]);
+    }
+    return rules;
+}
+/** Whether a `_headers` pattern matches a request path (`/` + the relative path). */
+export function headerPatternMatches(pattern, path) {
+    if (pattern.endsWith('*'))
+        return path.startsWith(pattern.slice(0, -1));
+    return pattern === path;
+}
+/** The headers the `_headers` file adds for a relative path. */
+async function extraHeaders(source, rel) {
+    const out = {};
+    const file = await load(source, HEADERS_FILE);
+    if (!file)
+        return out;
+    for (const rule of parseHeadersFile(new TextDecoder().decode(file))) {
+        if (!headerPatternMatches(rule.pattern, `/${rel}`))
+            continue;
+        for (const [name, value] of rule.headers)
+            out[name.toLowerCase()] = value;
+    }
+    return out;
+}
+async function handle(source, req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { ...TEXT, allow: 'GET, HEAD' }).end('method not allowed\n');
+        return;
+    }
+    const rel = requestPath(req.url ?? '/');
+    // The headers file configures the server; it is not part of the site.
+    const found = rel === null || rel === HEADERS_FILE ? null : await resolveRequest(source, rel);
+    if (!found) {
+        res.writeHead(404, TEXT).end('not found\n');
+        return;
+    }
+    // A page path answered with the shell gets the app's base (see withBaseHref).
+    const body = found.path === 'index.html' && rel !== '' && rel !== 'index.html' ? withBaseHref(found.body) : found.body;
+    res.writeHead(200, {
+        ...(await extraHeaders(source, rel ?? '')),
+        'content-type': contentTypeOf(found.path),
+        'content-length': String(body.byteLength),
+        'cache-control': 'no-cache',
+    });
+    if (req.method === 'HEAD')
+        res.end();
+    else
+        res.end(body);
+}
+/** Starts the server; resolves once it is listening. */
+export function startStaticServer(options) {
+    const hostname = options.hostname ?? '127.0.0.1';
+    const server = createServer((req, res) => {
+        handle(options.source, req, res).catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500, TEXT);
+            res.end('internal error\n');
+        });
+    });
+    return new Promise((resolveStart, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, hostname, () => {
+            server.off('error', reject);
+            const { port } = server.address();
+            const host = hostname.includes(':') ? `[${hostname}]` : hostname;
+            resolveStart({
+                url: `http://${host}:${port}/`,
+                port,
+                close: () => new Promise((done, fail) => {
+                    server.closeAllConnections();
+                    server.close((err) => (err ? fail(err) : done()));
+                }),
+            });
+        });
+    });
+}
+//# sourceMappingURL=static-server.js.map

package/dist/commands/lib/static-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-server.js","sourceRoot":"","sources":["../../../src/commands/lib/static-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A small static file server for a built pwapp: correct content types, no\n * directory listings, no path escapes, and an SPA fallback to `index.html`\n * for page paths.\n */\nimport { createServer, type IncomingMessage, type ServerResponse } from 'node:http'\nimport { readFile, stat } from 'node:fs/promises'\nimport { extname, join, resolve, sep } from 'node:path'\nimport type { AddressInfo } from 'node:net'\nimport { withBaseHref } from '../../dev/shell.js'\n\nexport const CONTENT_TYPES: Readonly<Record<string, string>> = {\n  '.html': 'text/html; charset=utf-8',\n  '.js': 'text/javascript; charset=utf-8',\n  '.mjs': 'text/javascript; charset=utf-8',\n  '.json': 'application/json; charset=utf-8',\n  '.css': 'text/css; charset=utf-8',\n  '.svg': 'image/svg+xml',\n  '.map': 'application/json; charset=utf-8',\n  '.txt': 'text/plain; charset=utf-8',\n  '.png': 'image/png',\n  '.jpg': 'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.gif': 'image/gif',\n  '.webp': 'image/webp',\n  '.avif': 'image/avif',\n  '.ico': 'image/x-icon',\n  '.woff': 'font/woff',\n  '.woff2': 'font/woff2',\n  '.wasm': 'application/wasm',\n}\n\nexport function contentTypeOf(path: string): string {\n  return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream'\n}\n\n/** Where the files come from: a folder on disk, or files held in memory (an opened archive). */\nexport type StaticSource = { readonly dir: string } | { readonly files: ReadonlyMap<string, Uint8Array> }\n\nexport interface StaticServerOptions {\n  readonly source: StaticSource\n  /** 0 picks a free port. */\n  readonly port: number\n  /** Default 127.0.0.1. */\n  readonly hostname?: string\n}\n\nexport interface StaticServer {\n  readonly url: string\n  readonly port: number\n  close(): Promise<void>\n}\n\n/** The request path as a safe relative POSIX path, or null when it is malformed or escapes the root. */\nexport function requestPath(rawUrl: string): string | null {\n  let pathname: string\n  try {\n    pathname = decodeURIComponent(new URL(rawUrl, 'http://localhost').pathname)\n  } catch {\n    return null\n  }\n  if (pathname.includes('\\0') || pathname.includes('\\\\')) return null\n  const parts: string[] = []\n  for (const seg of pathname.split('/')) {\n    if (seg === '' || seg === '.') continue\n    if (seg === '..') return null\n    parts.push(seg)\n  }\n  return parts.join('/')\n}\n\nasync function load(source: StaticSource, rel: string): Promise<Uint8Array | null> {\n  if ('files' in source) return source.files.get(rel) ?? null\n  const root = resolve(source.dir)\n  const abs = resolve(join(root, ...rel.split('/')))\n  if (abs !== root && !abs.startsWith(root + sep)) return null\n  const st = await stat(abs).catch(() => null)\n  if (!st?.isFile()) return null\n  return new Uint8Array(await readFile(abs))\n}\n\n/** Resolves a request to a file: the path itself, `<path>/index.html`, then the SPA fallback for page paths. */\nexport async function resolveRequest(source: StaticSource, rel: string): Promise<{ path: string; body: Uint8Array } | null> {\n  const candidates = rel === '' ? ['index.html'] : [rel, `${rel}/index.html`]\n  // A path whose last segment has no extension is a page path: answer it with the shell.\n  if (rel !== '' && extname(rel) === '') candidates.push('index.html')\n  for (const path of candidates) {\n    const body = await load(source, path)\n    if (body) return { path, body }\n  }\n  return null\n}\n\nconst TEXT = { 'content-type': 'text/plain; charset=utf-8' }\n\n/** The static-host headers file a build writes beside `index.html`. */\nexport const HEADERS_FILE = '_headers'\n\n/** One rule of a `_headers` file: a path pattern and the headers it adds. */\nexport interface HeaderRule {\n  readonly pattern: string\n  readonly headers: readonly (readonly [string, string])[]\n}\n\n/**\n * Parses the `_headers` convention of static hosts: a line that starts at\n * column 0 is a path pattern (`/*`, `/assets/*`, `/about`), the indented\n * `Name: value` lines under it are the headers it adds. `#` lines are\n * comments.\n */\nexport function parseHeadersFile(text: string): HeaderRule[] {\n  const rules: { pattern: string; headers: [string, string][] }[] = []\n  for (const raw of text.split(/\\r?\\n/)) {\n    if (!raw.trim() || raw.trim().startsWith('#')) continue\n    if (!/^\\s/.test(raw)) {\n      rules.push({ pattern: raw.trim(), headers: [] })\n      continue\n    }\n    const at = raw.indexOf(':')\n    const rule = rules[rules.length - 1]\n    if (at > 0 && rule) rule.headers.push([raw.slice(0, at).trim(), raw.slice(at + 1).trim()])\n  }\n  return rules\n}\n\n/** Whether a `_headers` pattern matches a request path (`/` + the relative path). */\nexport function headerPatternMatches(pattern: string, path: string): boolean {\n  if (pattern.endsWith('*')) return path.startsWith(pattern.slice(0, -1))\n  return pattern === path\n}\n\n/** The headers the `_headers` file adds for a relative path. */\nasync function extraHeaders(source: StaticSource, rel: string): Promise<Record<string, string>> {\n  const out: Record<string, string> = {}\n  const file = await load(source, HEADERS_FILE)\n  if (!file) return out\n  for (const rule of parseHeadersFile(new TextDecoder().decode(file))) {\n    if (!headerPatternMatches(rule.pattern, `/${rel}`)) continue\n    for (const [name, value] of rule.headers) out[name.toLowerCase()] = value\n  }\n  return out\n}\n\nasync function handle(source: StaticSource, req: IncomingMessage, res: ServerResponse): Promise<void> {\n  if (req.method !== 'GET' && req.method !== 'HEAD') {\n    res.writeHead(405, { ...TEXT, allow: 'GET, HEAD' }).end('method not allowed\\n')\n    return\n  }\n  const rel = requestPath(req.url ?? '/')\n  // The headers file configures the server; it is not part of the site.\n  const found = rel === null || rel === HEADERS_FILE ? null : await resolveRequest(source, rel)\n  if (!found) {\n    res.writeHead(404, TEXT).end('not found\\n')\n    return\n  }\n  // A page path answered with the shell gets the app's base (see withBaseHref).\n  const body = found.path === 'index.html' && rel !== '' && rel !== 'index.html' ? withBaseHref(found.body) : found.body\n  res.writeHead(200, {\n    ...(await extraHeaders(source, rel ?? '')),\n    'content-type': contentTypeOf(found.path),\n    'content-length': String(body.byteLength),\n    'cache-control': 'no-cache',\n  })\n  if (req.method === 'HEAD') res.end()\n  else res.end(body)\n}\n\n/** Starts the server; resolves once it is listening. */\nexport function startStaticServer(options: StaticServerOptions): Promise<StaticServer> {\n  const hostname = options.hostname ?? '127.0.0.1'\n  const server = createServer((req, res) => {\n    handle(options.source, req, res).catch(() => {\n      if (!res.headersSent) res.writeHead(500, TEXT)\n      res.end('internal error\\n')\n    })\n  })\n  return new Promise((resolveStart, reject) => {\n    server.once('error', reject)\n    server.listen(options.port, hostname, () => {\n      server.off('error', reject)\n      const { port } = server.address() as AddressInfo\n      const host = hostname.includes(':') ? `[${hostname}]` : hostname\n      resolveStart({\n        url: `http://${host}:${port}/`,\n        port,\n        close: () =>\n          new Promise<void>((done, fail) => {\n            server.closeAllConnections()\n            server.close((err) => (err ? fail(err) : done()))\n          }),\n      })\n    })\n  })\n}\n"]}

package/dist/commands/pack.d.ts

@@ -0,0 +1,5 @@
+import type { Command, CommandIO, ParsedArgs } from './types.js';
+/** `<name>-<version>.pwpack`, where name is the last segment of the pack id. */
+export declare function archiveName(id: string, version: string): string;
+export declare function runPack(args: ParsedArgs, io: CommandIO): Promise<number>;
+export declare const pack: Command;