@stravica-ai/digital-operator-pa 0.1.39 → 0.1.41

package/dist/engineering-pa-scaffold/src/cli.mjs

@@ -1,4 +1,4 @@
-// pa-init — onboarding scaffolder.
+// pa-init: onboarding scaffolder.
 //
 // Verb routing + arg parsing + exit-code translation. Domain code lives in
 // `commands/`, prompts in `prompts.mjs`, file generation in `generator.mjs`,
@@ -14,25 +14,35 @@
 import { parseArgs } from 'node:util';
 
 import { runInit } from './commands/init.mjs';
+import { runInitWorkspaceExtension } from './commands/init-workspace-extension.mjs';
 
-const USAGE = `pa-init — scaffold a new personal-assistant operator repo
+const USAGE = `pa-init: scaffold a new personal-assistant operator repo, or a single workspace extension.
 
 Usage:
   pa-init --mode=solo [--name=PA_NAME] [--target=DIR] [--non-interactive] [--operator=NAME] [--purpose=TEXT]
+  pa-init workspace-extension <name> [--label=LABEL] [--section=SECTION] [--with-api] [--target=DIR]
   pa-init --help
 
 Modes:
   solo                  Single-operator instance, no team library (Phase 1)
-  lead                  Team-lead instance with team library (Phase 5 — not yet implemented)
-  member --invite=TOKEN Join an existing team library (Phase 5 — not yet implemented)
+  lead                  Team-lead instance with team library (Phase 5, not yet implemented)
+  member --invite=TOKEN Join an existing team library (Phase 5, not yet implemented)
+
+Sub-verbs:
+  workspace-extension   Scaffold one workspace-extension page inside an existing operator repo.
+                        Writes operator/extensions/workspace/<name>.html and appends nav.json.
+                        --with-api also writes an <name>-api.mjs stub exporting register(addRoute).
 
 Common flags:
   --name=PA_NAME        PA identity (kebab-case, lowercase, no spaces). Prompted if absent.
-  --target=DIR          Target directory. Prompted if absent. Must be empty or not exist.
+  --target=DIR          Target directory. Prompted if absent for --mode=solo; defaults to cwd for sub-verbs.
   --operator=NAME       Operator (human) name. Prompted if absent.
   --purpose=TEXT        One-line PA purpose statement. Defaults to a generic line.
   --non-interactive     Refuse to prompt; require all values via flags. CI-friendly.
   --skip-install        Skip post-scaffold pnpm install + pa status (for testing).
+  --label=LABEL         (workspace-extension) Sidebar label. Defaults to Title Case of the name.
+  --section=SECTION     (workspace-extension) Nav section header. Defaults to "Extensions".
+  --with-api            (workspace-extension) Also write an <name>-api.mjs register(addRoute) stub.
   -h, --help            Show this help.
 
 Exit codes:
@@ -40,11 +50,19 @@ Exit codes:
 `;
 
 /**
- * Entry point invoked by bin/pa-init. Returns nothing — exits the process
+ * Entry point invoked by bin/pa-init. Returns nothing; exits the process
  * directly with the resolved code. Throws are translated to exit code 3
  * (transport/IO) if they carry no `exitCode`; otherwise to the carried code.
  */
 export async function main(argv) {
+  // Sub-verb routing: a leading positional that names a known sub-verb
+  // routes to that command's own parser. This keeps the existing
+  // flag-driven `--mode=solo` shape backwards compatible (its argv never
+  // starts with a positional under `allowPositionals: false`).
+  if (argv[0] === 'workspace-extension') {
+    return runWorkspaceExtensionVerb(argv.slice(1));
+  }
+
   let parsed;
   try {
     parsed = parseArgs({
@@ -113,3 +131,62 @@ export async function main(argv) {
 function exitWith(code) {
   process.exit(code);
 }
+
+/**
+ * Parse and dispatch the `workspace-extension` sub-verb. The scaffolder's
+ * primary flow uses flag-driven mode routing; this verb takes a required
+ * positional (the extension name) so it gets its own parser.
+ */
+async function runWorkspaceExtensionVerb(rest) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        label: { type: 'string' },
+        section: { type: 'string' },
+        'with-api': { type: 'boolean' },
+        target: { type: 'string' },
+      },
+      strict: true,
+      allowPositionals: true,
+    });
+  } catch (err) {
+    process.stderr.write(`pa-init workspace-extension: ${err.message}\n`);
+    process.stderr.write(USAGE);
+    return exitWith(1);
+  }
+
+  if (parsed.values.help) {
+    process.stdout.write(USAGE);
+    return exitWith(0);
+  }
+
+  const positionals = parsed.positionals;
+  if (positionals.length === 0) {
+    process.stderr.write('pa-init workspace-extension: <name> is required\n');
+    process.stderr.write(USAGE);
+    return exitWith(1);
+  }
+  if (positionals.length > 1) {
+    process.stderr.write(
+      `pa-init workspace-extension: unexpected extra positionals: ${positionals.slice(1).join(' ')}\n`,
+    );
+    return exitWith(1);
+  }
+
+  try {
+    const code = await runInitWorkspaceExtension({
+      name: positionals[0],
+      label: parsed.values.label,
+      section: parsed.values.section,
+      withApi: parsed.values['with-api'] === true,
+      targetDir: parsed.values.target,
+    });
+    return exitWith(code ?? 0);
+  } catch (err) {
+    process.stderr.write(`pa-init workspace-extension: ${err.message || err}\n`);
+    return exitWith(err && typeof err.exitCode === 'number' ? err.exitCode : 3);
+  }
+}

package/dist/engineering-pa-scaffold/src/commands/init-workspace-extension.mjs

@@ -0,0 +1,234 @@
+// init-workspace-extension.mjs -- `pa-init workspace-extension <name>` orchestration.
+//
+// Scaffolds one workspace-extension page inside an existing operator repo:
+//
+//   operator/extensions/workspace/<name>.html         page skeleton
+//   operator/extensions/workspace/nav.json            appended (created if absent)
+//   operator/extensions/workspace/<name>-api.mjs      optional (--with-api)
+//
+// Design contract:
+//   - Idempotent. A second run with the same name warns and does not overwrite.
+//   - Nav merge preserves existing entries. Same-id collisions warn and are left
+//     alone (never silently overwritten). Malformed nav.json fails cleanly with
+//     exit 2 rather than corrupting the file.
+//   - Runs against the operator's cwd. The `--target` flag lets tests point at
+//     a temporary directory, but the default is `process.cwd()` on the theory
+//     that an operator invokes this from inside their own instance.
+//
+// Errors carry `exitCode`. The CLI translates to `process.exit`.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+/** Kebab-case validator: 2-40 chars, lowercase letters + digits + hyphen, starts with a letter. */
+const NAME_RE = /^[a-z][a-z0-9-]{1,39}$/;
+
+/**
+ * Entry point for `pa-init workspace-extension <name>`. Returns an exit code.
+ *
+ * @param {object} options
+ * @param {string} options.name          extension slug (kebab-case)
+ * @param {string} [options.label]       nav label (defaults to Title Case of name)
+ * @param {string} [options.section]     nav section (defaults to 'Extensions')
+ * @param {boolean} [options.withApi]    also write a `<name>-api.mjs` stub
+ * @param {string} [options.targetDir]   operator repo root (defaults to cwd)
+ */
+export async function runInitWorkspaceExtension(options) {
+  const name = String(options.name || '').trim();
+  if (!name) return usageError('workspace-extension: <name> is required');
+  if (!NAME_RE.test(name)) {
+    return usageError(
+      `workspace-extension: invalid name '${name}' (expected kebab-case, 2-40 chars, letters/digits/-, starts with a letter)`,
+    );
+  }
+
+  const section = String(options.section || 'Extensions');
+  const label = String(options.label || defaultLabel(name));
+  const targetDir = resolveTargetDir(options.targetDir);
+  const extDir = join(targetDir, 'operator', 'extensions', 'workspace');
+  const htmlPath = join(extDir, `${name}.html`);
+  const navPath = join(extDir, 'nav.json');
+  const apiPath = join(extDir, `${name}-api.mjs`);
+
+  await mkdir(extDir, { recursive: true });
+
+  const written = [];
+  const skipped = [];
+
+  if (existsSync(htmlPath)) {
+    skipped.push(`${htmlPath} (page already exists)`);
+  } else {
+    await writeFile(htmlPath, buildHtmlSkeleton({ name, label }), 'utf8');
+    written.push(htmlPath);
+  }
+
+  const navResult = await mergeNavEntry({ navPath, name, label, section });
+  if (navResult.action === 'created' || navResult.action === 'appended') {
+    written.push(`${navPath} (${navResult.action})`);
+  } else {
+    skipped.push(`${navPath} (${navResult.reason})`);
+  }
+
+  if (options.withApi) {
+    if (existsSync(apiPath)) {
+      skipped.push(`${apiPath} (api stub already exists)`);
+    } else {
+      await writeFile(apiPath, buildApiStub({ name }), 'utf8');
+      written.push(apiPath);
+    }
+  }
+
+  emitSummary({ written, skipped, name });
+  return 0;
+}
+
+/** Kebab -> Title Case: `standup` -> `Standup`, `my-jira-today` -> `My Jira Today`. */
+export function defaultLabel(name) {
+  return name
+    .split('-')
+    .filter(Boolean)
+    .map((s) => s[0].toUpperCase() + s.slice(1))
+    .join(' ');
+}
+
+function resolveTargetDir(dir) {
+  const raw = dir || process.cwd();
+  return isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+}
+
+/**
+ * Read nav.json (or start empty), append a `{ id, label, href, section }`
+ * entry for the extension, and rewrite the file. Same-id collisions are
+ * left alone; malformed JSON fails cleanly (exit 2). Never silently
+ * overwrites an existing entry.
+ *
+ * Returns `{ action: 'created' | 'appended' | 'skipped', reason?: string }`.
+ */
+export async function mergeNavEntry({ navPath, name, label, section }) {
+  const entry = {
+    id: name,
+    label,
+    href: `/${name}.html`,
+    section,
+  };
+
+  let entries;
+  let existed = false;
+  if (existsSync(navPath)) {
+    existed = true;
+    let raw;
+    try {
+      raw = await readFile(navPath, 'utf8');
+    } catch (err) {
+      const e = new Error(`workspace-extension: could not read ${navPath}: ${err.message}`);
+      e.exitCode = 3;
+      throw e;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      const e = new Error(
+        `workspace-extension: ${navPath} is not valid JSON (${err.message}); refusing to overwrite`,
+      );
+      e.exitCode = 2;
+      throw e;
+    }
+    if (!Array.isArray(parsed)) {
+      const e = new Error(
+        `workspace-extension: ${navPath} must be a JSON array of nav entries; refusing to overwrite`,
+      );
+      e.exitCode = 2;
+      throw e;
+    }
+    entries = parsed;
+  } else {
+    entries = [];
+  }
+
+  const collision = entries.find((it) => it && it.id === name);
+  if (collision) {
+    return {
+      action: 'skipped',
+      reason: `nav entry id '${name}' already registered (left as-is)`,
+    };
+  }
+
+  entries.push(entry);
+  await mkdir(dirname(navPath), { recursive: true });
+  await writeFile(navPath, JSON.stringify(entries, null, 2) + '\n', 'utf8');
+  return { action: existed ? 'appended' : 'created' };
+}
+
+/**
+ * The static-page skeleton written for `<name>.html`. Kept minimal on
+ * purpose: the operator's PA fills in the real content on the next
+ * dispatch, and a heavier template would just be deleted.
+ */
+export function buildHtmlSkeleton({ name, label }) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(label)}</title>
+  <link rel="stylesheet" href="/core/tools/workspace/app/shell.css" />
+</head>
+<body>
+  <main class="page">
+    <h1>${escapeHtml(label)}</h1>
+    <!-- workspace-extension:${name} -->
+    <p>Replace this with the real page. Data lives under <code>/__api/${name}/...</code> if you scaffolded the api stub.</p>
+  </main>
+</body>
+</html>
+`;
+}
+
+/**
+ * The `<name>-api.mjs` stub. Exports `register(addRoute)` and wires one
+ * placeholder GET route so a fresh scaffold responds 200 without further
+ * work. The operator replaces the handler when they build the real page.
+ */
+export function buildApiStub({ name }) {
+  return `// ${name}-api.mjs -- workspace-extension API routes for /${name}.html.
+//
+// Exports \`register(addRoute)\`; the workspace server imports this at
+// startup and calls it. Pass \`{ crossOrigin: true }\` as a fourth
+// addRoute argument only for routes that legitimately accept requests
+// from another origin (e.g. a bookmarklet); the default guards Origin
+// and Sec-Fetch-Site.
+
+export function register(addRoute) {
+  addRoute('GET', '/__api/${name}/ping', (_req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, extension: '${name}' }));
+  });
+}
+`;
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function emitSummary({ written, skipped, name }) {
+  process.stdout.write(`pa-init workspace-extension: ${name}\n`);
+  for (const w of written) process.stdout.write(`  wrote   ${w}\n`);
+  for (const s of skipped) process.stdout.write(`  skipped ${s}\n`);
+  if (skipped.length === 0) {
+    process.stdout.write('\nNext: fill in the page content, restart the workspace to pick up the nav entry.\n');
+  } else {
+    process.stdout.write('\nAt least one file was left as-is. Rerun after resolving, or delete the existing file first.\n');
+  }
+}
+
+function usageError(message) {
+  process.stderr.write(`${message}\n`);
+  return 1;
+}

package/dist/engineering-pa-scaffold/src/commands/init.mjs

@@ -85,16 +85,17 @@ function writeNextStepMessage(config) {
   const { paName, targetDir } = config;
   const lines = [
     '',
-    'Next step — start your PA:',
+    'Next step - start your PA:',
     '',
     `  cd ${targetDir}`,
-    '  pa session',
+    '  pnpm exec pa session',
     '',
-    'Optional: add a shell alias for muscle memory. Add this to ~/.zshrc or ~/.bashrc:',
+    'Optional: add a one-word shell alias so you can start a session from anywhere.',
+    'Add this line to ~/.zshrc (zsh) or ~/.bashrc (bash), then reload the shell:',
     '',
-    `  alias ${paName}='pa session'`,
+    `  alias ${paName}='cd ${targetDir} && pnpm exec pa session'`,
     '',
-    `After reloading your shell, just type \`${paName}\` to start a session.`,
+    `After reloading, typing \`${paName}\` starts a session.`,
     '',
   ];
   process.stdout.write(lines.join('\n'));