phronesis 1.0.0

package/src/export.js

@@ -0,0 +1,136 @@
+import { resolve, relative, isAbsolute, dirname, basename, join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fse from 'fs-extra';
+import chalk from 'chalk';
+import { exportExcludeGlobs } from './layout.js';
+
+const execFileAsync = promisify(execFile);
+
+// True if `child` is `parent` or nested under it. Used to refuse writing the
+// tarball inside the directory being tarred (self-inclusion).
+function isInsideOrEqual(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+// Recognize a Phronesis installation by its registry marker — same contract init
+// uses. Export is read-only; it never writes into the install it tars.
+async function isPhronesisInstall(dir) {
+  return fse.pathExists(join(dir, '.phronesis', 'registry.json'));
+}
+
+// Tar (gzip) a Phronesis installation into a portable archive. Strips nothing
+// canonical: the export is a faithful snapshot of plain Markdown + config, with
+// relative symlinks preserved as symlinks (tar does not dereference by default),
+// so the extracted tree opens in Obsidian/VS Code with zero Phronesis runtime —
+// the export emancipation invariant (specs/security.md).
+//
+// The ONLY things stripped are the transient/non-canonical set (privacy-sensitive
+// event logs, disposable renders, OS cruft) — the same set the install .gitignore
+// omits, from a single source of truth (layout.js). No API keys are present to
+// strip: keys live in the OS keychain, never in installation files (security.md).
+export async function exportInstallation({ dir, out } = {}) {
+  const installDir = resolve(process.cwd(), dir || '.');
+
+  if (!(await fse.pathExists(installDir))) {
+    console.error(`Nothing to export: ${installDir} does not exist.`);
+    process.exitCode = 1;
+    return { cancelled: true };
+  }
+
+  if (!(await isPhronesisInstall(installDir))) {
+    console.error(
+      `Refusing to export ${installDir}: it is not a Phronesis installation ` +
+        '(.phronesis/registry.json not found). Pass the installation directory.',
+    );
+    process.exitCode = 1;
+    return { cancelled: true };
+  }
+
+  const outPath = out
+    ? resolve(process.cwd(), out)
+    : join(dirname(installDir), `${basename(installDir)}.tar.gz`);
+
+  // Never write the archive inside the tree being tarred — it would race against
+  // its own inclusion and grow the install with a disposable artifact. Lexical
+  // check first (catches the obvious case without touching the filesystem).
+  if (isInsideOrEqual(outPath, installDir)) {
+    return refuseSelfInclusion(outPath);
+  }
+
+  try {
+    await fse.ensureDir(dirname(outPath));
+  } catch (err) {
+    console.error(`Cannot create the export destination ${dirname(outPath)}: ${err.message}`);
+    process.exitCode = 1;
+    return { cancelled: true, error: err.message };
+  }
+
+  // Defense in depth: re-check after resolving symlinks, so an --out path that
+  // points into the install via a symlinked parent can't slip past the lexical
+  // guard. ensureDir above is a no-op when the parent is a symlink to an existing
+  // dir, so nothing was written into the install before this check.
+  const installReal = await fse.realpath(installDir);
+  const outReal = join(await fse.realpath(dirname(outPath)), basename(outPath));
+  if (isInsideOrEqual(outReal, installReal)) {
+    return refuseSelfInclusion(outPath);
+  }
+
+  // Write to a unique temp path and rename on success, so an interrupted or failed
+  // tar never leaves a corrupt-but-valid-looking archive in place of a good one
+  // (the export's promise is a faithful, trustworthy snapshot).
+  const tmpOut = `${outPath}.partial-${process.pid}`;
+  const excludes = exportExcludeGlobs().map((g) => `--exclude=${g}`);
+
+  // -C <parent> <name>: archive the install as a single top-level dir. No -h, so
+  // symlinks are stored as symlinks and survive the round-trip. Args passed as an
+  // array (not a shell string) so paths can't be interpreted as shell.
+  try {
+    await execFileAsync('tar', [
+      '-czf',
+      tmpOut,
+      ...excludes,
+      '-C',
+      dirname(installDir),
+      basename(installDir),
+    ]);
+    await fse.move(tmpOut, outPath, { overwrite: true });
+  } catch (err) {
+    await fse.remove(tmpOut).catch(() => {});
+    if (err.code === 'ENOENT') {
+      console.error(
+        'Export needs the `tar` command, which was not found. It ships with macOS ' +
+          'and Linux (the V1 supported platforms).',
+      );
+    } else {
+      console.error(`Export failed: ${err.message}`);
+    }
+    process.exitCode = 1;
+    return { cancelled: true, error: err.message };
+  }
+
+  printSuccess(installDir, outPath);
+  return { installDir, out: outPath };
+}
+
+function refuseSelfInclusion(outPath) {
+  console.error(
+    `Refusing to write the export inside the installation (${outPath}). ` +
+      'Choose an --out path outside the installation directory.',
+  );
+  process.exitCode = 1;
+  return { cancelled: true };
+}
+
+function printSuccess(installDir, outPath) {
+  console.log();
+  console.log('Installation exported.');
+  console.log();
+  console.log(`  ${chalk.bold(outPath)}`);
+  console.log(chalk.dim(`    a faithful snapshot of ${basename(installDir)}`));
+  console.log(chalk.dim('    plain Markdown plus config, relative symlinks preserved'));
+  console.log();
+  console.log(chalk.dim('  Opens anywhere, no Phronesis required. Yours to keep.'));
+  console.log();
+}

package/src/guard.js

@@ -0,0 +1,89 @@
+// `phronesis guard` — stdin-only pre-answer adapter glue. The guard brain lives in
+// @phronesis/core; this file reads the prompt from stdin, validates execution context,
+// and formats the surface-agnostic result.
+
+import { runContextRelevanceGuard } from '@phronesis/core';
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function parseGuardInput(raw) {
+  const text = String(raw ?? '');
+  const trimmed = text.trim();
+  if (trimmed.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object' && typeof parsed.prompt === 'string') {
+        return { prompt: parsed.prompt, session_id: parsed.session_id };
+      }
+      return { error: 'JSON stdin must include a string prompt field.' };
+    } catch {
+      return { error: 'malformed JSON stdin; pass raw text or a JSON envelope with a string prompt field.' };
+    }
+  }
+  return { prompt: text };
+}
+
+function printableResult(result) {
+  if (!result.fired) return '';
+  return result.packet || '';
+}
+
+export async function runGuard({ dir, session, surface, actor, domain, json = false } = {}) {
+  if (!dir) {
+    console.error('guard: --dir <install> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  const resolvedActor = actor || process.env.PHRONESIS_ACTOR || 'agent';
+  const resolvedSurface = surface || 'cli';
+
+  try {
+    const input = parseGuardInput(await readStdin());
+    if (input.error) {
+      console.error(`guard: ${input.error}`);
+      process.exitCode = 1;
+      return null;
+    }
+    if (!input.prompt || !input.prompt.trim()) {
+      console.error('guard: prompt is required on stdin (raw text or {"prompt": "..."} JSON).');
+      process.exitCode = 1;
+      return null;
+    }
+    if (input.session_id && session && input.session_id !== session) {
+      console.error('guard: stdin session_id does not match --session.');
+      process.exitCode = 1;
+      return null;
+    }
+    if (!session) {
+      console.error('guard: --session <id> is required.');
+      process.exitCode = 1;
+      return null;
+    }
+
+    const result = await runContextRelevanceGuard({
+      dir,
+      cwd: process.cwd(),
+      prompt: input.prompt,
+      session,
+      surface: resolvedSurface,
+      actor: resolvedActor,
+      domain,
+      env: process.env,
+    });
+    if (json) console.log(JSON.stringify(result));
+    else {
+      const text = printableResult(result);
+      if (text) console.log(text);
+    }
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`guard: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}

package/src/hooks.js

@@ -0,0 +1,230 @@
+// `phronesis hooks` — the session-boundary hook support surface (core-0013 / T4.2;
+// change 0010 D4; packet decisions H7/H8). CLI glue only (D7): the due computation,
+// the authoritative `outcome.due` emission, and the sweep-marker read live in
+// @phronesis/core (session-hooks.js). The scaffolded Claude Code hook scripts
+// (.phronesis/hooks/session-start.sh / session-sweep.sh) shell out to these.
+
+import {
+  ENUMS,
+  resolveInstall,
+  runDueCheck,
+  runScheduleDueCheck,
+  sweepStatus,
+  beginSkillInvocation,
+  completeActiveSkillInvocation,
+  abandonActiveSkillInvocation,
+  sweepStaleSkillInvocation,
+} from '@phronesis/core';
+
+function installOrFail(dir) {
+  const r = resolveInstall({ dir });
+  if (r.error) {
+    console.error(r.error);
+    process.exitCode = 1;
+    return null;
+  }
+  return r.root;
+}
+
+// Session-start due-check: emits one `outcome.due` per due decision AND one `schedule.due`
+// per due schedule-registry entry (the V1 authoritative emitters — event-log.md rows;
+// change 0042 folds the schedule half into this same command so an existing install's
+// scaffolded session-start.sh — which already calls `phronesis hooks due-check` — surfaces
+// schedules with NO shell-script change, just a CLI update: the Claude hook path stays
+// byte-compatible). The print IS the surface integration: a Claude Code SessionStart hook's
+// stdout is injected into the session context (Codex wraps the same stdout into its
+// additionalContext envelope), so this output is what surfaces both the decision artifacts
+// (hooks.md `on_review_date_due`) and the operator's own committed cadence
+// (`on_schedule_due`, classification `acknowledged`, the 0038 posture).
+export async function runHooksDueCheck({ session, dir, actor, surface } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!session) {
+    console.error('hooks due-check: --session <id> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  const resolvedActor = actor || process.env.PHRONESIS_ACTOR || 'agent';
+  const resolvedSurface = surface || 'cli';
+  try {
+    const { due } = await runDueCheck({ installRoot, session, actor: resolvedActor, surface: resolvedSurface });
+    if (!due.length) {
+      console.log('No decisions due for review.');
+    } else {
+      console.log(`Phronesis due-check: ${due.length} decision(s) due for review.`);
+      for (const d of due) {
+        const parts = d.decision_path.split('/');
+        const domain = parts[1];
+        const name = parts[parts.length - 1].replace(/\.md$/, '');
+        const overdue = d.days_overdue === 0 ? 'due today' : `${d.days_overdue} day(s) overdue`;
+        console.log(`\n  ${d.decision_path} — ${overdue} (review_date ${d.review_date})`);
+        console.log(
+          `    record the outcome: phronesis act record_outcome --domain ${domain} --session ${session} --json '{"target":"decisions/${name}","outcome_status":"<${ENUMS.outcome_status.join('|')}>","lesson":"<what you learned>"}'`,
+        );
+      }
+    }
+    // Schedule half (change 0042): a malformed schedule.json is a SEPARATE failure domain —
+    // it degrades to zero due entries here (validate/doctor own the fault), never breaking the
+    // decision due-check above.
+    const { due: scheduleDue } = await runScheduleDueCheck({ installRoot, session, actor: resolvedActor, surface: resolvedSurface });
+    if (scheduleDue.length) {
+      console.log(`\nPhronesis schedule: ${scheduleDue.length} item(s) due.`);
+      for (const s of scheduleDue) {
+        const overdue = s.days_overdue === 0 ? 'due now' : `${s.days_overdue} day(s) overdue`;
+        console.log(`\n  ${s.schedule_id} — ${s.kind}:${s.target} — ${overdue}`);
+        if (s.kind === 'cli_verb' || s.kind === 'connector_pull') {
+          console.log(`    run now: phronesis due run ${s.schedule_id}`);
+        }
+        console.log(`    mark done: phronesis due complete ${s.schedule_id}`);
+      }
+    }
+    process.exitCode = 0;
+    return due;
+  } catch (err) {
+    console.error(`hooks due-check: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// Sweep status: has this session emitted its capture-sweep marker (`session.end` with a
+// `sweep` payload — `sweep.candidates: 0` is the honest negative)? Prints `swept` or
+// `pending`; exits 0 when swept, 1 when pending — the scaffolded Stop-hook script keys
+// its block-once decision on the stdout word.
+export async function runHooksSweepStatus({ session, dir, json = false } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!session) {
+    console.error('hooks sweep-status: --session <id> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const status = await sweepStatus({ installRoot, session });
+    if (json) {
+      console.log(JSON.stringify(status));
+    } else {
+      console.log(status.swept ? 'swept' : 'pending');
+    }
+    process.exitCode = status.swept ? 0 : 1;
+    return status;
+  } catch (err) {
+    console.error(`hooks sweep-status: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+function parseHookPayload(label, payload) {
+  try {
+    return payload === undefined ? {} : JSON.parse(payload);
+  } catch {
+    console.error(`${label}: --payload must be valid JSON.`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// The operator-facing copy for the J1 zero-capture warning (core-0027). The POLICY (when
+// to warn) is @phronesis/core's meshZeroWarning; this is presentation only.
+function meshZeroWarningMessage(w) {
+  return (
+    `Phronesis: the heavy skill "${w.skill_name}" completed with 0 mesh enrichments ` +
+    `(no links_updated across ${w.action_types_committed} committed action(s)). A substantive ` +
+    'skill that banks nothing is usually a missed capture — intended? (specs/hooks.md on_skill_complete)'
+  );
+}
+
+export async function runHooksSkillStart({ dir, payload } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  const hookInput = parseHookPayload('hooks skill-start', payload);
+  if (!hookInput) return null;
+  try {
+    const result = await beginSkillInvocation({ installRoot, hookInput });
+    if (result.started) console.log(result.record.invocation_id);
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`hooks skill-start: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runHooksSkillComplete({ session, dir, payload, boundaryEvent, json = false } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!session) {
+    console.error('hooks skill-complete: --session <id> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  const hookInput = parseHookPayload('hooks skill-complete', payload);
+  if (!hookInput) return null;
+  if (boundaryEvent && !hookInput.hook_event_name) hookInput.hook_event_name = boundaryEvent;
+  try {
+    const result = await completeActiveSkillInvocation({
+      installRoot,
+      session,
+      hookInput,
+      reason: boundaryEvent || 'stop',
+    });
+    // (Schedule advancement for a completed `kind: skill` target now happens in core's
+    // completeActiveSkillInvocation — the single authoritative skill.completed boundary, so it
+    // fires on EVERY completion path, incl. next-start-closes-prior; change 0042 / Codex round-3.)
+    // J1 (core-0027): surface the zero-capture warning to the OPERATOR. As a
+    // Stop-hook stdout JSON, a top-level `systemMessage` is shown to the user,
+    // non-blocking, exit 0 (Claude Code hook output contract); session-sweep.sh passes
+    // this stdout through. --json keeps the full machine result for programmatic callers.
+    // No warning ⇒ nothing on stdout (the swept-session Stop output stays empty).
+    if (json) {
+      console.log(JSON.stringify(result));
+    } else if (result?.warning) {
+      console.log(JSON.stringify({ systemMessage: meshZeroWarningMessage(result.warning) }));
+    }
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`hooks skill-complete: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runHooksSkillAbandon({ dir, payload, json = false } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  const hookInput = parseHookPayload('hooks skill-abandon', payload);
+  if (!hookInput) return null;
+  try {
+    const result = await abandonActiveSkillInvocation({ installRoot, hookInput });
+    if (json) console.log(JSON.stringify(result));
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`hooks skill-abandon: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export async function runHooksSkillSweepStale({ session, dir, json = false } = {}) {
+  const installRoot = installOrFail(dir);
+  if (!installRoot) return null;
+  if (!session) {
+    console.error('hooks skill-sweep-stale: --session <id> is required.');
+    process.exitCode = 1;
+    return null;
+  }
+  try {
+    const result = await sweepStaleSkillInvocation({ installRoot, session });
+    if (json) console.log(JSON.stringify(result));
+    process.exitCode = 0;
+    return result;
+  } catch (err) {
+    console.error(`hooks skill-sweep-stale: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}