@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-scaffold/README.md

@@ -0,0 +1,164 @@
+# @stravica-ai/engineering-pa-scaffold
+
+Identity: `@stravica-ai/engineering-pa-scaffold` — `pa-init` scaffolder + onboarding flows.
+
+## Status
+
+| Mode | Status | Lands in |
+|---|---|---|
+| `--mode=solo` | **implemented** | Phase 1 Task 5 |
+| `--mode=lead` | not implemented | Phase 3 |
+| `--mode=member` | not implemented | Phase 5 |
+
+Workspace-internal: `"private": true`, not individually published. The
+operator-facing surface ships via the public `@stravica-ai/digital-operator-pa`
+package; `pa-init` is exposed as one of its bin entries.
+
+## Install / invoke
+
+The bin is `pa-init`. After installing `@stravica-ai/digital-operator-pa` into an
+empty staging directory (or invoking via `pnpm exec`), run:
+
+```bash
+pa-init --mode=solo --name=dave --operator=Baz --target=./dave-instance
+```
+
+Or interactively, with three prompts:
+
+```bash
+pa-init --mode=solo
+# Operator name (the human this PA serves, e.g. 'Baz'): Baz
+# PA name (kebab-case identity, e.g. 'dave'):           dave
+# Target directory [/current/cwd]:                      /home/baz/dave
+```
+
+## Commands
+
+```bash
+pa-init --help                   # usage; exits 0
+pa-init --mode=solo              # interactive solo onboarding
+pa-init --mode=solo --name=NAME --operator=OP --target=DIR
+                                 # flag-driven solo onboarding
+pa-init --mode=solo --non-interactive --name=... --operator=... --target=...
+                                 # CI mode; refuses to prompt
+pa-init --mode=lead              # exits 2 ("not implemented in Phase 1")
+pa-init --mode=member --invite=T # exits 2 ("not implemented in Phase 1")
+```
+
+### Flags
+
+| Flag | Purpose |
+|---|---|
+| `--mode=MODE` | `solo` \| `lead` \| `member` (only `solo` ships in Phase 1) |
+| `--name=PA_NAME` | PA identity. Kebab-case, lowercase, 2-40 chars, starts with a letter. |
+| `--operator=NAME` | Operator (human) name. Free-form, 1-80 chars. |
+| `--target=DIR` | Target directory. Must be empty or not exist. |
+| `--purpose=TEXT` | Optional one-line PA purpose statement. Has a sane default. |
+| `--non-interactive` | Refuse to prompt. Requires all values via flags. CI-friendly. |
+| `--skip-install` | Skip the post-scaffold `pnpm install` + `pa status` check (test-friendly). |
+| `-h`, `--help` | Show usage, exit 0. |
+
+## Exit codes (tooling standard §6)
+
+| Code | Meaning |
+|---|---|
+| 0 | OK |
+| 1 | Usage error — invalid flags, missing required values in non-interactive mode, invalid PA name, non-empty target. |
+| 2 | Operational failure — `pnpm install` or `pa status` exited non-zero. |
+| 3 | Transport / IO failure — couldn't spawn a subprocess. |
+
+## What `--mode=solo` generates
+
+```
+{target}/
+├── CLAUDE.md                          # PA identity, rendered from the bundled template
+├── README.md                          # operator-repo orientation
+├── package.json                       # depends on @stravica-ai/digital-operator-pa
+├── .gitignore                         # node, .session, .vault keys, *.pid, runs.jsonl
+├── .nvmrc                             # 24
+├── .git/                              # initialised so desk's .git-walk works
+├── operator/
+│   ├── profile/profile.md             # placeholder; PA leads intake to fill
+│   ├── knowledge/
+│   │   ├── domains.json               # base 5 domains per methodology
+│   │   └── index.json                 # empty
+│   └── extensions/
+│       ├── manifest.json              # empty (extensions land in Phase 2)
+│       ├── roles/, tools/, workspace/ # empty, .gitkeep'd
+├── agents/{paName}/
+│   ├── CLAUDE.md                      # same as root CLAUDE.md (PA identity)
+│   ├── journal.md                     # empty stub
+│   ├── next-session.md                # empty stub
+│   ├── spawn-log.json                 # {"version":"1.0", "spawns":[]}
+│   └── staging/                       # empty, .gitkeep'd
+├── work/                              # empty, .gitkeep'd
+├── projects/                          # empty, .gitkeep'd
+├── schedules/                         # empty, .gitkeep'd
+└── .vault/                            # empty, .gitkeep'd
+```
+
+### Base knowledge domains
+
+Seeded into `operator/knowledge/domains.json` per the knowledge-system
+methodology (5 core engineering-PA domains):
+
+- `engineering` — the discipline
+- `ops` — operational rules and process
+- `agent-ops` — agentic team management
+- `knowledge-meta` — the librarian and methodology
+- `operator-profile` — who the operator is
+
+Operators extend per-deployment (finance, sales, legal, etc.); the scaffolder
+ships only the core set.
+
+## Project layout
+
+```
+packages/scaffold/
+  bin/pa-init                  # node shebang shim — imports src/cli.mjs
+  index.mjs                    # package entry — re-exports public surface
+  package.json                 # name, version, bin: pa-init
+  README.md                    # this file (the spec)
+  src/
+    cli.mjs                    # arg parsing, verb routing, exit-code translation
+    prompts.mjs                # interactive prompts + validators (readline seam)
+    generator.mjs              # PURE: plan-of-files given a config
+    runner.mjs                 # CHOKEPOINT: writes files, spawns pnpm/pa/git
+    commands/
+      init.mjs                 # --mode=solo orchestration
+  templates/
+    CLAUDE.md.template         # PA identity template, {PA_NAME}/{OPERATOR_NAME}/{PURPOSE}/{COMMUNICATION_STYLE} tokens
+    operator-README.md.template# operator-repo README template
+  test/
+    index.test.mjs             # package surface
+    cli.test.mjs               # bin-via-child-process tests (parsing + exit codes + happy path)
+    prompts.test.mjs           # validator + promptValues seam tests
+    generator.test.mjs         # pure plan-composition tests
+    runner.test.mjs            # chokepoint tests with fake-spawn seam
+```
+
+### Chokepoint pattern (tooling standard §7)
+
+Every external effect is in `src/runner.mjs`:
+
+- `writePlan(targetDir, plan)` — sole filesystem-write surface
+- `runProcess({ cmd, args, cwd, seam })` — sole `child_process.spawn` surface
+- `installDeps`, `paStatus`, `initGitRepo` — thin wrappers around `runProcess`
+
+Nothing else in the scaffolder reaches the disk or the OS. Tests inject a
+fake `seam.spawn` to verify framing without executing real subprocesses.
+
+## Tests
+
+```bash
+pnpm --filter @stravica-ai/engineering-pa-scaffold test
+# or, from the package directory:
+node --test 'test/**/*.test.mjs'
+```
+
+## The tooling standard
+
+This tool complies with [the tooling standard](../../CONTRIBUTING.md#standards)
+in full: JS only, zero npm runtime deps, `node:test`, `node:util.parseArgs`
+with `strict: true`, camelCase JSON, chokepoint pattern for external effects,
+README-as-contract, four-exit-code contract.

package/dist/engineering-pa-scaffold/bin/pa-init

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-scaffold/index.mjs

@@ -0,0 +1,42 @@
+// @stravica-ai/engineering-pa-scaffold — pa-init scaffolder + onboarding flows.
+//
+// Phase 1 Task 5 lands the real --mode=solo flow. --mode=lead and
+// --mode=member follow in Phase 3/5.
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const name = './';
+export const version = '0.1.1';
+export const modes = ['solo', 'lead', 'member'];
+
+/**
+ * Absolute path to the bundled CLAUDE.md template. The scaffolder reads
+ * this file, substitutes `{PA_NAME}` / `{OPERATOR_NAME}` / `{PURPOSE}` /
+ * `{COMMUNICATION_STYLE}` placeholders, and writes the result to the
+ * operator repo's `CLAUDE.md` and `agents/{paName}/CLAUDE.md`.
+ */
+export const CLAUDE_MD_TEMPLATE = resolve(__dirname, 'templates', 'CLAUDE.md.template');
+
+/** Absolute path to the operator-repo README template. */
+export const OPERATOR_README_TEMPLATE = resolve(
+  __dirname,
+  'templates',
+  'operator-README.md.template',
+);
+
+export { main } from './src/cli.mjs';
+export { runInit } from './src/commands/init.mjs';
+export {
+  buildPlan,
+  buildPlanFromTemplates,
+  buildRenderConfig,
+  BASE_DOMAINS,
+} from './src/generator.mjs';
+export {
+  validateOperatorName,
+  validatePaName,
+  validateTargetPath,
+} from './src/prompts.mjs';

package/dist/engineering-pa-scaffold/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@stravica-ai/engineering-pa-scaffold",
+  "version": "0.1.1",
+  "description": "pa-init scaffolder + onboarding flows (solo, lead, member).",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "bin": {
+    "pa-init": "bin/pa-init"
+  },
+  "private": true,
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none 'test/**/*.test.mjs'"
+  },
+  "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."
+}

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

@@ -0,0 +1,115 @@
+// 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`,
+// and the spawn/IO chokepoint in `runner.mjs`. cli.mjs is the only module
+// that knows about `process.exit`.
+//
+// Exit codes (tooling standard §6):
+//   0  ok
+//   1  usage error
+//   2  logical / operational failure
+//   3  transport / IO failure
+
+import { parseArgs } from 'node:util';
+
+import { runInit } from './commands/init.mjs';
+
+const USAGE = `pa-init — scaffold a new personal-assistant operator repo
+
+Usage:
+  pa-init --mode=solo [--name=PA_NAME] [--target=DIR] [--non-interactive] [--operator=NAME] [--purpose=TEXT]
+  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)
+
+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.
+  --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).
+  -h, --help            Show this help.
+
+Exit codes:
+  0  ok | 1  usage error | 2  operational failure | 3  transport/IO failure
+`;
+
+/**
+ * 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) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        mode: { type: 'string' },
+        name: { type: 'string' },
+        target: { type: 'string' },
+        operator: { type: 'string' },
+        purpose: { type: 'string' },
+        invite: { type: 'string' },
+        'non-interactive': { type: 'boolean' },
+        'skip-install': { type: 'boolean' },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`pa-init: ${err.message}\n`);
+    process.stderr.write(USAGE);
+    return exitWith(1);
+  }
+
+  if (parsed.values.help) {
+    process.stdout.write(USAGE);
+    return exitWith(0);
+  }
+
+  const mode = parsed.values.mode;
+  if (!mode) {
+    process.stderr.write('pa-init: --mode is required (solo | lead | member)\n');
+    process.stderr.write(USAGE);
+    return exitWith(1);
+  }
+
+  if (mode === 'lead' || mode === 'member') {
+    process.stderr.write(
+      `pa-init: --mode=${mode} is not implemented in Phase 1 (lands in Phase 3/5)\n`,
+    );
+    return exitWith(2);
+  }
+
+  if (mode !== 'solo') {
+    process.stderr.write(`pa-init: unknown mode '${mode}' (expected solo | lead | member)\n`);
+    process.stderr.write(USAGE);
+    return exitWith(1);
+  }
+
+  try {
+    const code = await runInit({
+      paName: parsed.values.name,
+      targetDir: parsed.values.target,
+      operatorName: parsed.values.operator,
+      purpose: parsed.values.purpose,
+      nonInteractive: parsed.values['non-interactive'] === true,
+      skipInstall: parsed.values['skip-install'] === true,
+    });
+    return exitWith(code ?? 0);
+  } catch (err) {
+    process.stderr.write(`pa-init: ${err.message || err}\n`);
+    return exitWith(err && typeof err.exitCode === 'number' ? err.exitCode : 3);
+  }
+}
+
+function exitWith(code) {
+  process.exit(code);
+}

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

@@ -0,0 +1,169 @@
+// init.mjs — `pa-init --mode=solo` orchestration.
+//
+// Flow:
+//   1. Gather config: prompts (interactive) or flag-only (non-interactive).
+//   2. Build the plan (pure generator).
+//   3. Pre-flight: target dir empty / missing.
+//   4. Write the plan to disk.
+//   5. Init git (so desk's .git-walk finds the operator repo root).
+//   6. (Optional) Install dependencies + run `pa status` to verify boot.
+//
+// Errors carry an `exitCode`. The CLI translates to `process.exit`.
+
+import { resolve } from 'node:path';
+
+import { buildPlan, buildRenderConfig } from '../generator.mjs';
+import {
+  defaultSeam,
+  promptValues,
+  validateOperatorName,
+  validatePaName,
+  validateTargetPath,
+} from '../prompts.mjs';
+import {
+  assertTargetIsEmptyOrMissing,
+  initGitRepo,
+  installDeps,
+  paStatus,
+  writePlan,
+} from '../runner.mjs';
+
+/**
+ * Entry point for `--mode=solo`. Returns an exit code.
+ */
+export async function runInit(options) {
+  const config = await gatherConfig(options);
+
+  process.stdout.write(`\npa-init: scaffolding ${config.paName} for ${config.operatorName}\n`);
+  process.stdout.write(`         target: ${config.targetDir}\n`);
+
+  await assertTargetIsEmptyOrMissing(config.targetDir);
+
+  const plan = await buildPlan(config);
+  await writePlan(config.targetDir, plan);
+  process.stdout.write(`         wrote ${countEntries(plan)} entries\n`);
+
+  const gitCode = await initGitRepo({ targetDir: config.targetDir });
+  if (gitCode !== 0) {
+    process.stderr.write(`pa-init: git init exited with ${gitCode}\n`);
+    return 2;
+  }
+
+  if (options.skipInstall) {
+    process.stdout.write('         skip-install set — leaving install + pa status to caller\n');
+    process.stdout.write('\npa-init: done.\n');
+    writeNextStepMessage(config);
+    return 0;
+  }
+
+  process.stdout.write('\npa-init: running pnpm install …\n');
+  const installCode = await installDeps({ targetDir: config.targetDir });
+  if (installCode !== 0) {
+    process.stderr.write(`pa-init: pnpm install exited with ${installCode}\n`);
+    return 2;
+  }
+
+  process.stdout.write('\npa-init: running pa status …\n');
+  const statusCode = await paStatus({ targetDir: config.targetDir });
+  if (statusCode !== 0) {
+    process.stderr.write(`pa-init: pa status exited with ${statusCode}\n`);
+    return 2;
+  }
+
+  process.stdout.write('\npa-init: done.\n');
+  writeNextStepMessage(config);
+  return 0;
+}
+
+/**
+ * Emit the "next step" guidance after a successful pa-init. Points the
+ * operator at `pa session` — the standard entry point for booting their
+ * PA — and offers an optional shell alias keyed off the PA name they
+ * just scaffolded.
+ */
+function writeNextStepMessage(config) {
+  const { paName, targetDir } = config;
+  const lines = [
+    '',
+    'Next step — start your PA:',
+    '',
+    `  cd ${targetDir}`,
+    '  pa session',
+    '',
+    'Optional: add a shell alias for muscle memory. Add this to ~/.zshrc or ~/.bashrc:',
+    '',
+    `  alias ${paName}='pa session'`,
+    '',
+    `After reloading your shell, just type \`${paName}\` to start a session.`,
+    '',
+  ];
+  process.stdout.write(lines.join('\n'));
+}
+
+async function gatherConfig(options) {
+  const targetDirDefault = resolve(process.cwd());
+  const supplied = {
+    paName: options.paName || null,
+    operatorName: options.operatorName || null,
+    targetDir: options.targetDir || null,
+    targetDirDefault,
+  };
+
+  let resolvedValues;
+  if (options.nonInteractive) {
+    const missing = [];
+    if (!supplied.paName) missing.push('--name');
+    if (!supplied.operatorName) missing.push('--operator');
+    if (!supplied.targetDir) missing.push('--target');
+    if (missing.length > 0) {
+      const e = new Error(
+        `non-interactive mode requires all values via flags; missing: ${missing.join(', ')}`,
+      );
+      e.exitCode = 1;
+      throw e;
+    }
+    resolvedValues = applyValidatorsOrThrow({
+      paName: supplied.paName,
+      operatorName: supplied.operatorName,
+      targetDir: supplied.targetDir,
+    });
+  } else {
+    const seam = defaultSeam();
+    try {
+      resolvedValues = await promptValues(seam, supplied);
+    } finally {
+      seam.close();
+    }
+  }
+
+  return buildRenderConfig({
+    paName: resolvedValues.paName,
+    operatorName: resolvedValues.operatorName,
+    targetDir: resolvedValues.targetDir,
+    purpose: options.purpose,
+  });
+}
+
+function applyValidatorsOrThrow(supplied) {
+  const checks = [
+    ['name', supplied.paName, validatePaName],
+    ['operator', supplied.operatorName, validateOperatorName],
+    ['target', supplied.targetDir, validateTargetPath],
+  ];
+  const out = {};
+  const keys = { name: 'paName', operator: 'operatorName', target: 'targetDir' };
+  for (const [flag, value, validator] of checks) {
+    const result = validator(value);
+    if (!result.ok) {
+      const e = new Error(`invalid --${flag}: ${result.reason}`);
+      e.exitCode = 1;
+      throw e;
+    }
+    out[keys[flag]] = result.value;
+  }
+  return out;
+}
+
+function countEntries(plan) {
+  return plan.length;
+}