@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,354 @@
+// generator.mjs — pure scaffolding plan.
+//
+// Given a normalised config, return a list of `{ kind, path, contents? }`
+// entries that the runner writes to disk. NO IO HERE. All filesystem
+// effects live in runner.mjs.
+//
+// kind: 'dir' (mkdir -p) | 'file' (write file with contents) | 'json'
+// (stringify + write).
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Path to the CLAUDE.md template (relative to this module). */
+export const CLAUDE_MD_TEMPLATE_PATH = resolve(__dirname, '..', 'templates', 'CLAUDE.md.template');
+
+/** Path to the operator README template (relative to this module). */
+export const OPERATOR_README_TEMPLATE_PATH = resolve(
+  __dirname,
+  '..',
+  'templates',
+  'operator-README.md.template',
+);
+
+/**
+ * The base set of knowledge domains seeded into every fresh PA instance.
+ * Per the methodology doc: engineering, ops, agent-ops, knowledge-meta,
+ * operator-profile.
+ */
+export const BASE_DOMAINS = [
+  { id: 'engineering', label: 'Engineering — the discipline (patterns, standards, decisions, tech debt)' },
+  { id: 'ops', label: 'Operational rules and process' },
+  { id: 'agent-ops', label: 'Agentic team management (roles, identity, roster, autonomy envelopes)' },
+  { id: 'knowledge-meta', label: 'The librarian and methodology' },
+  { id: 'operator-profile', label: 'Who the operator is — context, preferences, constraints' },
+];
+
+const DEFAULT_PURPOSE =
+  'Be a self-learning personal assistant who learns the operator deeply over time and acts on their behalf with increasing autonomy.';
+
+const DEFAULT_COMMUNICATION_STYLE =
+  'Casual, direct, no filler. Voice opinions with reasoning. Light humour welcome; obsequiousness is not.';
+
+/**
+ * Build a normalised render config from raw inputs.
+ */
+export function buildRenderConfig(input) {
+  const generatedAt = input.generatedAt || new Date().toISOString();
+  return {
+    paName: input.paName,
+    operatorName: input.operatorName,
+    purpose: input.purpose && input.purpose.trim().length > 0 ? input.purpose.trim() : DEFAULT_PURPOSE,
+    communicationStyle:
+      input.communicationStyle && input.communicationStyle.trim().length > 0
+        ? input.communicationStyle.trim()
+        : DEFAULT_COMMUNICATION_STYLE,
+    targetDir: resolve(input.targetDir),
+    generatedAt,
+    pkgVersion: input.pkgVersion || '^0.1.0',
+  };
+}
+
+/**
+ * Render the CLAUDE.md template with the config. Pure token replacement
+ * (regex, no template engine). Template tokens follow the existing v2
+ * convention from Task 4: {PA_NAME}, {OPERATOR_NAME}, {PURPOSE},
+ * {COMMUNICATION_STYLE}.
+ */
+export function renderClaudeMd(template, config) {
+  return template
+    .replaceAll('{PA_NAME}', config.paName)
+    .replaceAll('{OPERATOR_NAME}', config.operatorName)
+    .replaceAll('{PURPOSE}', config.purpose)
+    .replaceAll('{COMMUNICATION_STYLE}', config.communicationStyle);
+}
+
+/**
+ * Render the operator-repo README template. Uses the same token set as
+ * CLAUDE.md.template for consistency.
+ */
+export function renderOperatorReadme(template, config) {
+  return template
+    .replaceAll('{PA_NAME}', config.paName)
+    .replaceAll('{OPERATOR_NAME}', config.operatorName);
+}
+
+/**
+ * Build the operator-repo package.json contents.
+ *
+ * Per the brief: the generated repo depends on `@stravica-ai/digital-operator-pa`
+ * (the public surface). For Task 5 verification via `pnpm link`, the test
+ * harness ALSO links `@stravica-ai/engineering-pa-cli` to expose the actual
+ * `pa` / `desk` bins. The generated package.json reflects the
+ * post-publication wiring; the test setup is a layer on top.
+ */
+export function buildOperatorPackageJson(config) {
+  return {
+    name: `${config.paName}-operator`,
+    version: '0.0.1',
+    private: true,
+    type: 'module',
+    description: `Personal-assistant operator repo for ${config.operatorName} (PA: ${config.paName}).`,
+    engines: { node: '>=24' },
+    dependencies: {
+      '@stravica-ai/digital-operator-pa': config.pkgVersion,
+    },
+    scripts: {
+      pa: 'pa',
+      desk: 'desk',
+      status: 'pa status',
+    },
+  };
+}
+
+/**
+ * Build the .gitignore contents for the operator repo. Per tooling
+ * standard §16: per-host operational files must be gitignored.
+ */
+export function buildGitignore() {
+  return [
+    '# Dependencies',
+    'node_modules/',
+    '.pnpm-store/',
+    '',
+    '# Environment',
+    '.env',
+    '.env.local',
+    '.env.*.local',
+    '',
+    '# Editor',
+    '.vscode/',
+    '.idea/',
+    '*.swp',
+    '*.swo',
+    '*~',
+    '',
+    '# OS',
+    '.DS_Store',
+    'Thumbs.db',
+    '',
+    '# Session-local state (per-host)',
+    '.session/',
+    '.state/',
+    '',
+    '# Per-host operational artefacts (tooling standard §16)',
+    '*.pid',
+    '*.log',
+    'runs.jsonl',
+    '.cache/',
+    '',
+    '# Vault — only the encrypted store is tracked; raw key material never',
+    '.vault/age-key.txt',
+    '.vault/*.key',
+    '',
+    '# Workspace runtime',
+    '.ws.pid',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Build the operator/config/preferences.json contents.
+ *
+ * This file is the operator's machine-readable preferences store. The
+ * `pa session` verb keys off the `paName` field to locate the agent
+ * directory; future verbs and the librarian will lean on the same file
+ * for things like communication style and the workspace port.
+ *
+ * All keys are camelCase per the firm rule.
+ */
+export function buildPreferencesJson(config) {
+  return {
+    paName: config.paName,
+    operator: { name: config.operatorName, role: 'Operator' },
+    pa: { name: capitalise(config.paName), role: 'PA' },
+    communicationStyle: config.communicationStyle,
+    workspacePort: 4200,
+    generatedAt: config.generatedAt,
+  };
+}
+
+function capitalise(s) {
+  if (typeof s !== 'string' || s.length === 0) return s;
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Build the operator/extensions/manifest.json contents. */
+export function buildExtensionsManifest(config) {
+  return {
+    version: '1.0',
+    generatedAt: config.generatedAt,
+    extensions: [],
+    note: 'Extensions land in Phase 2. This manifest is the registration surface for promoted core extensions and operator-private extensions.',
+  };
+}
+
+/** Build the operator/knowledge/domains.json contents. */
+export function buildDomainsJson(config) {
+  return {
+    version: '1.0',
+    generatedAt: config.generatedAt,
+    domains: BASE_DOMAINS.map((d) => ({ id: d.id, label: d.label })),
+  };
+}
+
+/** Build the operator/knowledge/index.json contents (empty top-level index). */
+export function buildKnowledgeIndexJson(config) {
+  return {
+    version: '1.0',
+    generatedAt: config.generatedAt,
+    principles: 'principles.md',
+    domains: [],
+  };
+}
+
+/** Build the agents/{paName}/spawn-log.json contents. */
+export function buildSpawnLogJson(config) {
+  return {
+    version: '1.0',
+    description: `Log of all agent delegations by ${config.paName}. Used for distillation learning and team improvement.`,
+    spawns: [],
+  };
+}
+
+/** Build the operator/profile/profile.md placeholder. */
+export function buildProfileMd(config) {
+  return [
+    `# ${config.operatorName}`,
+    '',
+    'Operator profile. The librarian distills observations from your PA into this file over time.',
+    'For now it is a placeholder — your PA will lead an intake conversation early on to capture',
+    'preferences, working style, vocabulary, and the immediate context the PA needs to be useful.',
+    '',
+    `Generated by pa-init at ${config.generatedAt}.`,
+    '',
+  ].join('\n');
+}
+
+/** Build the agents/{paName}/journal.md placeholder. */
+export function buildJournalMd(config) {
+  return [
+    `# Journal — ${config.paName}`,
+    '',
+    'Self-improvement notes. What went well, what to do differently, capability gaps to address.',
+    'Append timestamped entries here as you reflect on each session.',
+    '',
+  ].join('\n');
+}
+
+/** Build the agents/{paName}/next-session.md placeholder. */
+export function buildNextSessionMd(config) {
+  return [
+    '# Next session',
+    '',
+    `(Empty — generated at ${config.generatedAt}.)`,
+    '',
+    'Maintain this file continuously. The "Top priority — start here" section is operator-facing.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Build the staging/.gitkeep contents. Empty directories cannot be tracked
+ * by git directly; we drop a .gitkeep marker so the directory is preserved.
+ */
+export function buildGitkeep() {
+  return '';
+}
+
+/**
+ * Compose the full plan. Returns an ordered list of `{ kind, path, contents }`
+ * relative to `config.targetDir`. The runner resolves the paths and writes
+ * them.
+ */
+export async function buildPlan(config) {
+  const claudeTemplate = await readFile(CLAUDE_MD_TEMPLATE_PATH, 'utf8');
+  const operatorReadmeTemplate = await readFile(OPERATOR_README_TEMPLATE_PATH, 'utf8');
+  return buildPlanFromTemplates(config, { claudeTemplate, operatorReadmeTemplate });
+}
+
+/**
+ * Pure: composes the plan given pre-loaded template strings. The
+ * non-template-loading variant is exposed so tests can drive the
+ * generator without touching the disk.
+ */
+export function buildPlanFromTemplates(config, templates) {
+  const { paName } = config;
+  const claudeMd = renderClaudeMd(templates.claudeTemplate, config);
+  const readmeMd = renderOperatorReadme(templates.operatorReadmeTemplate, config);
+  const pkg = buildOperatorPackageJson(config);
+  const gitignore = buildGitignore();
+  const manifest = buildExtensionsManifest(config);
+  const domains = buildDomainsJson(config);
+  const knowledgeIndex = buildKnowledgeIndexJson(config);
+  const spawnLog = buildSpawnLogJson(config);
+  const profile = buildProfileMd(config);
+  const journal = buildJournalMd(config);
+  const nextSession = buildNextSessionMd(config);
+
+  const dirs = [
+    'operator',
+    'operator/profile',
+    'operator/knowledge',
+    'operator/config',
+    'operator/extensions',
+    'operator/extensions/roles',
+    'operator/extensions/tools',
+    'operator/extensions/workspace',
+    `agents/${paName}`,
+    `agents/${paName}/staging`,
+    'work',
+    'projects',
+    'schedules',
+    '.vault',
+  ];
+
+  const plan = [];
+  for (const d of dirs) plan.push({ kind: 'dir', path: d });
+
+  plan.push({ kind: 'file', path: 'CLAUDE.md', contents: claudeMd });
+  plan.push({ kind: 'file', path: 'README.md', contents: readmeMd });
+  plan.push({ kind: 'json', path: 'package.json', contents: pkg });
+  plan.push({ kind: 'file', path: '.gitignore', contents: gitignore });
+  plan.push({ kind: 'file', path: '.nvmrc', contents: '24\n' });
+
+  plan.push({ kind: 'file', path: 'operator/profile/profile.md', contents: profile });
+  plan.push({ kind: 'json', path: 'operator/knowledge/domains.json', contents: domains });
+  plan.push({ kind: 'json', path: 'operator/knowledge/index.json', contents: knowledgeIndex });
+  plan.push({ kind: 'json', path: 'operator/config/preferences.json', contents: buildPreferencesJson(config) });
+  plan.push({ kind: 'json', path: 'operator/extensions/manifest.json', contents: manifest });
+
+  plan.push({ kind: 'file', path: `agents/${paName}/CLAUDE.md`, contents: claudeMd });
+  plan.push({ kind: 'file', path: `agents/${paName}/journal.md`, contents: journal });
+  plan.push({ kind: 'file', path: `agents/${paName}/next-session.md`, contents: nextSession });
+  plan.push({ kind: 'json', path: `agents/${paName}/spawn-log.json`, contents: spawnLog });
+
+  // Empty-directory markers — git won't track empty dirs.
+  for (const d of [
+    `agents/${paName}/staging`,
+    'work',
+    'projects',
+    'schedules',
+    '.vault',
+    'operator/extensions/roles',
+    'operator/extensions/tools',
+    'operator/extensions/workspace',
+  ]) {
+    plan.push({ kind: 'file', path: join(d, '.gitkeep'), contents: buildGitkeep() });
+  }
+
+  return plan;
+}

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

@@ -0,0 +1,125 @@
+// Interactive prompts for pa-init.
+//
+// Pure-ish: pure validation functions (testable directly) + a `promptValues`
+// driver that takes a `readLine` seam. The default seam wraps `node:readline`;
+// tests inject a fake seam.
+
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+/** kebab-case, lowercase, 2-40 chars, must start with a letter. */
+export function validatePaName(value) {
+  if (typeof value !== 'string') return { ok: false, reason: 'must be a string' };
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return { ok: false, reason: 'must be at least 2 characters' };
+  if (trimmed.length > 40) return { ok: false, reason: 'must be at most 40 characters' };
+  if (!/^[a-z][a-z0-9-]*$/.test(trimmed)) {
+    return {
+      ok: false,
+      reason: 'must be kebab-case, lowercase, start with a letter (e.g. "dave", "anna-pa")',
+    };
+  }
+  if (trimmed.endsWith('-') || trimmed.includes('--')) {
+    return { ok: false, reason: 'no trailing or doubled dashes' };
+  }
+  return { ok: true, value: trimmed };
+}
+
+/** Non-empty, 1-80 chars, trimmed. Allows letters / spaces / punctuation. */
+export function validateOperatorName(value) {
+  if (typeof value !== 'string') return { ok: false, reason: 'must be a string' };
+  const trimmed = value.trim();
+  if (trimmed.length < 1) return { ok: false, reason: 'must not be empty' };
+  if (trimmed.length > 80) return { ok: false, reason: 'must be at most 80 characters' };
+  return { ok: true, value: trimmed };
+}
+
+/**
+ * Target dir must be either:
+ *   - not exist (we will create it), OR
+ *   - exist and be empty (no entries other than dotfile-free check).
+ *
+ * The actual filesystem check is done by the runner — this helper only
+ * validates the *path-shape* (non-empty, absolute or relative).
+ */
+export function validateTargetPath(value) {
+  if (typeof value !== 'string') return { ok: false, reason: 'must be a string' };
+  const trimmed = value.trim();
+  if (trimmed.length < 1) return { ok: false, reason: 'must not be empty' };
+  return { ok: true, value: resolve(trimmed) };
+}
+
+/**
+ * Drive an interactive prompt sequence. `seam.ask(question) -> Promise<string>`
+ * is the only IO surface; tests substitute a scripted fake.
+ *
+ * `defaults` carries pre-populated values from CLI flags. The function
+ * prompts only for missing values (except operatorName which always prompts
+ * in interactive mode — there's no flag for it in the v1 contract... wait,
+ * there is. `--operator`. So we prompt only when missing).
+ */
+export async function promptValues(seam, defaults) {
+  const out = {};
+
+  out.operatorName = await ensureValid(
+    seam,
+    defaults.operatorName,
+    "Operator name (the human this PA serves, e.g. 'Baz'): ",
+    validateOperatorName,
+  );
+
+  out.paName = await ensureValid(
+    seam,
+    defaults.paName,
+    "PA name (kebab-case identity, e.g. 'dave'): ",
+    validatePaName,
+  );
+
+  out.targetDir = await ensureValid(
+    seam,
+    defaults.targetDir,
+    `Target directory [${defaults.targetDirDefault}]: `,
+    validateTargetPath,
+    defaults.targetDirDefault,
+  );
+
+  return out;
+}
+
+async function ensureValid(seam, presupplied, question, validator, fallback) {
+  if (presupplied != null && presupplied !== '') {
+    const result = validator(presupplied);
+    if (result.ok) return result.value;
+    const err = new Error(`invalid value '${presupplied}': ${result.reason}`);
+    err.exitCode = 1;
+    throw err;
+  }
+  // Loop until valid.
+  for (;;) {
+    const raw = await seam.ask(question);
+    const supplied = raw === '' && fallback != null ? fallback : raw;
+    const result = validator(supplied);
+    if (result.ok) return result.value;
+    seam.write(`  ✗ ${result.reason}\n`);
+  }
+}
+
+/**
+ * Default seam — wraps `node:readline`. Returns an object exposing
+ * `ask(question) -> Promise<string>` and `write(text)` so the prompts
+ * module never imports readline directly.
+ */
+export function defaultSeam() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask(question) {
+      return new Promise((res) => rl.question(question, (answer) => res(answer)));
+    },
+    write(text) {
+      process.stdout.write(text);
+    },
+    close() {
+      rl.close();
+    },
+  };
+}

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

@@ -0,0 +1,142 @@
+// runner.mjs — chokepoint for external effects.
+//
+// All filesystem writes for the scaffolder happen here. All process spawns
+// (pnpm install, pa status, git init) happen here. Nothing else in the
+// scaffolder reaches the disk or the OS.
+//
+// Tests inject a `{ spawn }` seam to verify framing without executing
+// real subprocesses. The filesystem writes are exercised against a real
+// tmp dir in the end-to-end test.
+
+import { mkdir, readdir, stat, writeFile } from 'node:fs/promises';
+import { spawn as realSpawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+/**
+ * Pre-flight: verify the target dir is either missing or empty. Throws
+ * with exitCode=1 on a clobber risk.
+ */
+export async function assertTargetIsEmptyOrMissing(targetDir) {
+  let entries;
+  try {
+    entries = await readdir(targetDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return; // OK: we'll create it.
+    throw err;
+  }
+  const visible = entries.filter((name) => !name.startsWith('.DS_Store'));
+  if (visible.length > 0) {
+    const e = new Error(
+      `target directory is not empty: ${targetDir} (contains ${visible.length} entries)`,
+    );
+    e.exitCode = 1;
+    throw e;
+  }
+}
+
+/**
+ * Write the plan to disk under `targetDir`. Creates parent dirs as needed.
+ * Order matters: directories first, then files.
+ */
+export async function writePlan(targetDir, plan) {
+  // Phase 1 — all directories. mkdir recursive is idempotent and creates
+  // parents.
+  for (const entry of plan) {
+    if (entry.kind !== 'dir') continue;
+    const abs = join(targetDir, entry.path);
+    await mkdir(abs, { recursive: true });
+  }
+
+  // Phase 2 — files. Each file's parent dir is guaranteed by mkdir on the
+  // parent if it isn't in the plan as an explicit 'dir' entry.
+  for (const entry of plan) {
+    if (entry.kind === 'dir') continue;
+    const abs = join(targetDir, entry.path);
+    await mkdir(dirname(abs), { recursive: true });
+    if (entry.kind === 'json') {
+      await writeFile(abs, JSON.stringify(entry.contents, null, 2) + '\n', 'utf8');
+    } else if (entry.kind === 'file') {
+      await writeFile(abs, entry.contents, 'utf8');
+    } else {
+      const e = new Error(`runner: unknown plan-entry kind '${entry.kind}' for ${entry.path}`);
+      e.exitCode = 2;
+      throw e;
+    }
+  }
+}
+
+/**
+ * Run a subprocess and stream its stdio. Returns the exit code.
+ *
+ * `cwd` is the working directory of the spawned process. `env` extends the
+ * parent env. `seam.spawn` is the injection point for tests; defaults to
+ * `node:child_process.spawn`.
+ */
+export async function runProcess({ cmd, args, cwd, env, seam }) {
+  const spawnFn = (seam && seam.spawn) || realSpawn;
+  return new Promise((resolve, reject) => {
+    const child = spawnFn(cmd, args, {
+      cwd,
+      env: { ...process.env, ...(env || {}) },
+      stdio: 'inherit',
+    });
+    child.on('error', (err) => {
+      const e = new Error(`spawn ${cmd}: ${err.message}`);
+      e.exitCode = 3;
+      reject(e);
+    });
+    child.on('close', (code) => resolve(code ?? 0));
+  });
+}
+
+/**
+ * Initialise a git repo at `targetDir`. The operator-repo conventions
+ * assume a `.git` directory at the root (desk's repo-walker depends on it).
+ */
+export async function initGitRepo({ targetDir, seam }) {
+  return runProcess({
+    cmd: 'git',
+    args: ['init', '--quiet', '--initial-branch=main'],
+    cwd: targetDir,
+    seam,
+  });
+}
+
+/**
+ * Install dependencies. Default uses pnpm; can be overridden via env or
+ * the seam for tests.
+ */
+export async function installDeps({ targetDir, seam }) {
+  return runProcess({
+    cmd: process.env.PA_INIT_PKG_MANAGER || 'pnpm',
+    args: ['install'],
+    cwd: targetDir,
+    seam,
+  });
+}
+
+/**
+ * Run `pa status` from inside the freshly-scaffolded repo. The exit code
+ * is the runner's signal to the operator that the instance booted.
+ */
+export async function paStatus({ targetDir, seam }) {
+  return runProcess({
+    cmd: join(targetDir, 'node_modules', '.bin', 'pa'),
+    args: ['status'],
+    cwd: targetDir,
+    seam,
+  });
+}
+
+/**
+ * Confirm a path exists and is a directory. Returns true/false; does not
+ * throw.
+ */
+export async function isDirectory(path) {
+  try {
+    const s = await stat(path);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}