@nfinitmonkeys/clan-engine 0.1.1 → 0.3.0

package/dist/inspect.js

@@ -51,6 +51,70 @@ function brainRootFor(tier, alphaName) {
         return `.brains/${(alphaName ?? '').toLowerCase()}`;
     return '.brain';
 }
+/** Vault presence at a root: a wiki/ dir or a .brain-meta.json. */
+function vaultExists(repo, r) {
+    return existsSync(join(repo, r, 'wiki')) || existsSync(join(repo, r, '.brain-meta.json'));
+}
+/** The vault an EXISTING load-brain SessionStart hook already points at
+ *  (repo-relative), when that directory still exists. The live hook is ground
+ *  truth: it names the vault sessions ACTUALLY load, so setup must never
+ *  repoint away from it (e.g. the jungle repo's debris-only .brain/ vs the
+ *  real .brains/obsidian the hook hydrates). */
+function hookedBrainRoot(repo) {
+    const raw = read(join(repo, '.claude', 'settings.json'));
+    if (raw === null)
+        return undefined;
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const entries = Array.isArray(doc?.hooks?.SessionStart) ? doc.hooks.SessionStart : [];
+    for (const entry of entries) {
+        for (const h of entry?.hooks ?? []) {
+            const m = /(?:^|[\s"'=])((?:\$\{?CLAUDE_PROJECT_DIR\}?\/)?[^\s"']+)\/scripts\/load-brain\.(?:mjs|sh)/
+                .exec(h?.command ?? '');
+            if (!m)
+                continue;
+            const rel = m[1].replace(/^\$\{?CLAUDE_PROJECT_DIR\}?\//, '').replace(/^\.\//, '');
+            if (rel && !rel.startsWith('/') && !rel.includes('..') && existsSync(join(repo, rel)))
+                return rel;
+        }
+    }
+    return undefined;
+}
+/** An EXISTING vault at ANY known root. Precedence:
+ *   1. the vault a load-brain SessionStart hook already loads — wins outright;
+ *   2. vaults containing wiki/identity.md, in order .district/brain >
+ *      tier-default root > .brain > .brains/<alpha> > other .brains/*
+ *      (preferring 'obsidian') — a real identity beats debris (e.g. a
+ *      sources-only .brain/ left by a memory bridge);
+ *   3. bare-existing vaults in that same order;
+ *   4. none → undefined (tier default applies downstream).
+ *  Data safety: reconcile scaffolds at the detected root, never a tier-default
+ *  duplicate — and never away from the vault the live hook hydrates. */
+function detectBrainRoot(repo, tier, alphaName) {
+    const hooked = hookedBrainRoot(repo);
+    if (hooked)
+        return hooked;
+    const candidates = ['.district/brain', brainRootFor(tier, alphaName), '.brain'];
+    if (alphaName)
+        candidates.push(`.brains/${alphaName.toLowerCase()}`);
+    try {
+        const dirs = readdirSync(join(repo, '.brains')).filter(d => vaultExists(repo, `.brains/${d}`));
+        for (const d of [...dirs.filter(x => x === 'obsidian'), ...dirs.filter(x => x !== 'obsidian').sort()]) {
+            candidates.push(`.brains/${d}`);
+        }
+    }
+    catch { /* no .brains */ }
+    const uniq = [...new Set(candidates)].filter(c => c && !c.endsWith('/'));
+    const withIdentity = uniq.find(r => existsSync(join(repo, r, 'wiki', 'identity.md')));
+    if (withIdentity)
+        return withIdentity;
+    return uniq.find(r => vaultExists(repo, r));
+}
 export function inspect(repo, opts = {}) {
     const notes = [];
     const { tier, source: tierSource } = detectTier(repo, opts.tierFlag);
@@ -69,15 +133,48 @@ export function inspect(repo, opts = {}) {
             notes.push('.jungle/config.yaml is unparseable');
         }
     }
-    const connected = cfg?.jungle?.status === 'connected' || cfg?.jungle?.status === 'approved';
+    // 'registered' / 'onboarded' are older attach-era statuses pointing at a real
+    // Jungle (fleet: Funnel, Beacon) — flipping them to standalone would rewrite
+    // their packs with "the user is the approver" fiction. apiUrl is the
+    // connection intent (Funnel's apiKey is empty but its Jungle is real — the
+    // missing-key note below stays honest). Full creds with no status at all =
+    // legacy attach (old clan-ready treated apiUrl alone as connected).
+    const status = cfg?.jungle?.status;
+    const hasCreds = !!(cfg?.jungle?.apiUrl && cfg?.jungle?.alphaId && cfg?.jungle?.apiKey);
+    const connected = status === 'connected' || status === 'approved'
+        || ((status === 'registered' || status === 'onboarded') && !!cfg?.jungle?.apiUrl)
+        || (status === undefined && hasCreds);
     const mode = connected ? 'connected' : 'standalone';
-    const identity = cfg?.project?.name && cfg?.project?.alphaName ? {
+    // ── .district/district.config.yaml (the district box's identity) ──
+    let dcfg = null;
+    const dcfgRaw = read(join(repo, '.district', 'district.config.yaml'));
+    if (dcfgRaw !== null) {
+        try {
+            dcfg = YAML.parse(dcfgRaw);
+        }
+        catch {
+            notes.push('.district/district.config.yaml is unparseable');
+        }
+    }
+    // ── existing vault (any known root) — wins over the tier default ──
+    const existingBrainRoot = detectBrainRoot(repo, tier, dcfg?.district?.alphaName ?? cfg?.project?.alphaName);
+    const identity = dcfg?.district?.name && dcfg?.district?.alphaName ? {
+        name: dcfg.district.name,
+        alphaName: dcfg.district.alphaName,
+        description: dcfg.district.description ?? '',
+        tier,
+        mode,
+        alphaId: dcfg.district.alphaId,
+        boxPort: String(dcfg.http?.port ?? '7787'),
+        brainRoot: existingBrainRoot,
+    } : cfg?.project?.name && cfg?.project?.alphaName ? {
         name: cfg.project.name,
         alphaName: cfg.project.alphaName,
         description: cfg.project.description ?? '',
         tier,
         mode,
         alphaId: cfg.jungle?.alphaId,
+        brainRoot: existingBrainRoot,
         jungle: connected && cfg.jungle?.apiUrl && cfg.jungle?.alphaId && cfg.jungle?.apiKey
             ? { apiUrl: cfg.jungle.apiUrl, alphaId: cfg.jungle.alphaId, apiKey: cfg.jungle.apiKey }
             : undefined,
@@ -104,8 +201,8 @@ export function inspect(repo, opts = {}) {
             notes.push('.mcp.json is unparseable');
         }
     }
-    // ── brain (at the tier-aware root) ──
-    const bRoot = brainRootFor(tier, cfg?.project?.alphaName);
+    // ── brain (existing vault at any root > the tier-aware default) ──
+    const bRoot = existingBrainRoot ?? brainRootFor(tier, dcfg?.district?.alphaName ?? cfg?.project?.alphaName);
     let hasBrain = false;
     let brainLayoutVersion;
     const metaRaw = read(join(repo, bRoot, '.brain-meta.json'));
@@ -166,6 +263,6 @@ export function inspect(repo, opts = {}) {
         repo, os, isGit, tier, tierSource, mode, identity,
         hasConfig, configError, hasMcp, mcpServers,
         inventory: scanInventory(repo, { home: opts.home }),
-        hasBrain, brainLayoutVersion, state, notes,
+        hasBrain, brainLayoutVersion, brainRoot: existingBrainRoot, state, notes,
     };
 }

package/dist/inventory.d.ts

@@ -14,5 +14,7 @@ import type { InventoryItem } from './types.js';
 export declare function scanInventory(repo: string, opts?: {
     home?: string;
 }): InventoryItem[];
-/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+/** Write the manifest the awareness skill references. Returns the repo-relative
+ *  path. PROJECT scope only — global (~/.claude) assets are the operator's
+ *  private tooling and must not be persisted into a committable repo file. */
 export declare function writeInventoryManifest(repo: string, items: InventoryItem[]): string;

package/dist/inventory.js

@@ -126,11 +126,13 @@ export function scanInventory(repo, opts = {}) {
         return true;
     });
 }
-/** Write the manifest the awareness skill references. Returns the repo-relative path. */
+/** Write the manifest the awareness skill references. Returns the repo-relative
+ *  path. PROJECT scope only — global (~/.claude) assets are the operator's
+ *  private tooling and must not be persisted into a committable repo file. */
 export function writeInventoryManifest(repo, items) {
     const dir = join(repo, '.clan');
     mkdirSync(dir, { recursive: true });
-    const rel = items.map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null }));
+    const rel = items.filter(i => i.scope === 'project').map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null }));
     writeFileSync(join(dir, 'inventory.json'), JSON.stringify({ generatedBy: 'clan-engine', items: rel }, null, 2) + '\n', 'utf-8');
     return '.clan/inventory.json';
 }

package/dist/mcp.d.ts

@@ -17,6 +17,16 @@ export declare function jungleLocalServer(c: JungleCreds): {
     args: string[];
     env: Record<string, string>;
 };
+/** District-tier creds: the jungle-local server speaks to the LOCAL district
+ *  box (localhost:<boxPort>), not the cloud Jungle. Same server shape — only
+ *  the URL differs. The self-row key is only capturable at district init (the
+ *  box stores its hash); callers pass it via env, never argv. */
+export declare function districtBoxCreds(boxPort: string, alphaId: string, apiKey: string): JungleCreds;
+/** .mcp.json plan for a district — jungle-local → the local box. */
+export declare function planDistrictMcpJson(repo: string, boxPort: string, creds: {
+    alphaId: string;
+    apiKey: string;
+}, isGit: boolean): PlanAction[];
 /**
  * Produce the reconciliation action(s) for .mcp.json given the target creds.
  * Returns a 'merge' action (new file content) plus, when a fresh file is

package/dist/mcp.js

@@ -17,6 +17,17 @@ export function jungleLocalServer(c) {
         env.JUNGLE_HUMAN_EMAIL = c.humanEmail;
     return { command: 'npx', args: ['-y', '@nfinitmonkeys/jungle-mcp'], env };
 }
+/** District-tier creds: the jungle-local server speaks to the LOCAL district
+ *  box (localhost:<boxPort>), not the cloud Jungle. Same server shape — only
+ *  the URL differs. The self-row key is only capturable at district init (the
+ *  box stores its hash); callers pass it via env, never argv. */
+export function districtBoxCreds(boxPort, alphaId, apiKey) {
+    return { apiUrl: `http://localhost:${boxPort}`, alphaId, apiKey };
+}
+/** .mcp.json plan for a district — jungle-local → the local box. */
+export function planDistrictMcpJson(repo, boxPort, creds, isGit) {
+    return planMcpJson(repo, districtBoxCreds(boxPort, creds.alphaId, creds.apiKey), isGit);
+}
 /**
  * Produce the reconciliation action(s) for .mcp.json given the target creds.
  * Returns a 'merge' action (new file content) plus, when a fresh file is

package/dist/reconcile.js

@@ -63,6 +63,11 @@ function reconcileClaudeMd(repo, i) {
 }
 export function reconcile(identity, ins, opts = {}) {
     const repo = ins.repo;
+    // Data safety: an EXISTING vault at any known root wins over the tier
+    // default — re-tiering (or the jungle repo's own .brain/) must never mint a
+    // duplicate vault. inspect detects it; every template downstream honors it.
+    if (ins.brainRoot && !identity.brainRoot)
+        identity = { ...identity, brainRoot: ins.brainRoot };
     const actions = [];
     // 1. CLAUDE.md declaration
     actions.push(reconcileClaudeMd(repo, identity));
@@ -83,19 +88,34 @@ export function reconcile(identity, ins, opts = {}) {
     // 4. managed .claude surface (awareness SKILL.md + tier command pack + hook script)
     for (const f of claudeSurface(identity))
         actions.push(reconcileFile(repo, f));
-    // 5. inventory manifest (refresh when changed — idempotent otherwise)
-    const inv = scanInventory(repo);
+    // 5. inventory manifest (refresh when changed — idempotent otherwise).
+    //    PROJECT scope only: persisting the operator's global ~/.claude asset
+    //    list would leak private tooling metadata into every (committable) repo
+    //    and churn on every machine change. Global items stay in the in-memory
+    //    InspectResult for the wizard.
+    const inv = scanInventory(repo).filter(i => i.scope === 'project');
     const invContent = JSON.stringify({ generatedBy: 'clan-engine', items: inv.map(i => ({ kind: i.kind, name: i.name, scope: i.scope, description: i.description ?? null })) }, null, 2) + '\n';
     const invExisting = read(repo, '.clan/inventory.json');
     if (invExisting === null)
-        actions.push({ kind: 'create', path: '.clan/inventory.json', content: invContent, note: `inventory ${inv.length} existing asset(s) the Alpha can use` });
+        actions.push({ kind: 'create', path: '.clan/inventory.json', content: invContent, note: `inventory ${inv.length} existing project asset(s) the Alpha can use` });
     else if (invExisting !== invContent)
-        actions.push({ kind: 'update', path: '.clan/inventory.json', content: invContent, note: `refresh inventory (${inv.length} asset(s))` });
+        actions.push({ kind: 'update', path: '.clan/inventory.json', content: invContent, note: `refresh inventory (${inv.length} project asset(s))` });
     else
         actions.push({ kind: 'skip', path: '.clan/inventory.json', note: 'inventory unchanged', reason: 'unchanged' });
     // 6. .mcp.json (connected mode)
     if (opts.jungle)
         actions.push(...planMcpJson(repo, opts.jungle, ins.isGit));
+    // 6b. journals + backups under .claude/.clan-engine/ can embed live-key
+    //     artifacts (a backed-up .mcp.json on merge) — never committable. Ignore
+    //     the dir in the same run that gitignores .mcp.json itself.
+    if (ins.isGit) {
+        const gi = read(repo, '.gitignore') ?? '';
+        if (!gi.split('\n').some(l => l.trim() === '.claude/.clan-engine/')) {
+            const priorAppend = actions.some(a => a.kind === 'append' && a.path === '.gitignore');
+            const prefix = priorAppend || gi.length === 0 || gi.endsWith('\n') ? '' : '\n';
+            actions.push({ kind: 'append', path: '.gitignore', content: prefix + '.claude/.clan-engine/\n', note: 'gitignore .claude/.clan-engine/ (journals + backups may hold backed-up keys)' });
+        }
+    }
     // 7. SessionStart brain hook (tier-aware command)
     actions.push(...planBrainHook(repo, identity));
     // 8. brain scaffold — create-only (never overwrite accumulated brain pages)

package/dist/sanitize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Secret / infra / PHI filter — the non-negotiable gate on anything that goes
+ * into a brain. A clan's brain_index is cross-clan-readable by council/master
+ * keys, and repo docs + session memory routinely hold ssh keys, prod creds,
+ * connection strings, and (for HIPAA clans) PHI. Every candidate body is scanned
+ * BEFORE it becomes a brain page; anything that trips is HELD BACK, never
+ * written. Reasons are LABELS ONLY — the matched secret text is never returned,
+ * so a scan result is safe to log.
+ *
+ * PHI scanning is ON BY DEFAULT (opt out with { hipaa: false }): a false-positive
+ * hold-back is cheap; a PHI leak is catastrophic.
+ */
+export interface ScanResult {
+    flagged: boolean;
+    reasons: string[];
+}
+/**
+ * Scan text for secrets + infra identifiers (always) and PHI (unless
+ * hipaa:false is explicitly passed — PHI is scanned by default).
+ */
+export declare function scanSensitive(text: string, opts?: {
+    hipaa?: boolean;
+}): ScanResult;

package/dist/sanitize.js

@@ -0,0 +1,71 @@
+/**
+ * Secret / infra / PHI filter — the non-negotiable gate on anything that goes
+ * into a brain. A clan's brain_index is cross-clan-readable by council/master
+ * keys, and repo docs + session memory routinely hold ssh keys, prod creds,
+ * connection strings, and (for HIPAA clans) PHI. Every candidate body is scanned
+ * BEFORE it becomes a brain page; anything that trips is HELD BACK, never
+ * written. Reasons are LABELS ONLY — the matched secret text is never returned,
+ * so a scan result is safe to log.
+ *
+ * PHI scanning is ON BY DEFAULT (opt out with { hipaa: false }): a false-positive
+ * hold-back is cheap; a PHI leak is catastrophic.
+ */
+const SECRET_PATTERNS = [
+    ['private-key-block', /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP |ENCRYPTED )?PRIVATE KEY-----/],
+    ['ssh-public-key', /\bssh-(?:rsa|ed25519|dss)\s+AAAA[0-9A-Za-z+/]{20,}/],
+    ['aws-access-key-id', /\b(?:AKIA|ASIA|AGPA|AIDA)[0-9A-Z]{16}\b/],
+    ['aws-secret-assignment', /\b(?:aws.?)?secret.?access.?key\b\s*[:=]\s*\S{16,}/i],
+    ['gcp-api-key', /\bAIza[0-9A-Za-z_\-]{35,}/],
+    ['gcp-service-account', /\b[a-z0-9-]+@[a-z0-9-]+\.iam\.gserviceaccount\.com\b|"private_key_id"\s*:/],
+    ['azure-storage-key', /\bAccountKey\s*=\s*[A-Za-z0-9+/=]{20,}/i],
+    ['azure-sas', /\bSharedAccessSignature\b|[?&]sig=[A-Za-z0-9%]{20,}/],
+    ['stripe-key', /\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{16,}\b|\bwhsec_[A-Za-z0-9]{16,}\b/],
+    ['twilio-key', /\b(?:SK|AC)[0-9a-f]{32}\b/],
+    ['sendgrid-key', /\bSG\.[A-Za-z0-9_\-]{16,}\.[A-Za-z0-9_\-]{16,}\b/],
+    ['github-token', /\bgh[pousr]_[A-Za-z0-9]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b/],
+    ['slack-token', /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/],
+    ['openai-anthropic-cortex-key', /\bsk-(?:ant-|cortex-|proj-|live-)?[A-Za-z0-9_-]{16,}\b/],
+    ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/],
+    ['bearer-or-authorization', /\b(?:authorization|bearer)\b\s*:?\s*(?:bearer\s+)?[A-Za-z0-9._\-]{16,}/i],
+    ['uri-with-embedded-creds', /\b[a-z][a-z0-9+.\-]*:\/\/[^\s:@/]+:[^\s@/]+@/i],
+    ['dotnet-connection-string', /\b(?:Password|Pwd)\s*=\s*[^;\s]{6,};?/i],
+    ['generic-secret-assignment', /\b(?:password|passwd|secret|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token|bearer|token)\b\s*[:=]\s*['"]?[A-Za-z0-9/_+=.\-]{10,}/i],
+    ['env-assignment-high-entropy', /^[A-Z][A-Z0-9_]{2,}\s*=\s*\S{16,}$/m],
+];
+const INFRA_PATTERNS = [
+    ['aws-instance-id', /\bi-[0-9a-f]{8,17}\b/],
+    ['aws-sg-id', /\bsg-[0-9a-f]{8,17}\b/],
+    ['aws-subnet-or-vpc-id', /\b(?:subnet|vpc|eni|vol|ami)-[0-9a-f]{8,17}\b/],
+    ['aws-account-arn', /\b\d{12}\.dkr\.ecr\b|arn:aws:[^\s]*:\d{12}:/i],
+    ['rds-or-cloud-endpoint', /\b[a-z0-9-]+\.[a-z0-9]+\.[a-z0-9-]+\.(?:rds|elasticache|redshift)\.amazonaws\.com\b/i],
+    ['private-ipv4', /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3})\b/],
+    ['private-ipv6', /\b(?:fd[0-9a-f]{2}:[0-9a-f:]{2,}|fe80:[0-9a-f:]{2,})/i],
+    ['ssh-to-ip', /\bssh\b[^\n]*@\d{1,3}(?:\.\d{1,3}){3}\b/i],
+    ['key-file-ref', /\b[\w-]{3,}\.(?:pem|ppk)\b|(?:\/|~\/)?\.ssh\/[\w.-]+/],
+];
+const PHI_PATTERNS = [
+    ['ssn', /\b\d{3}[-. ]\d{2}[-. ]\d{4}\b|\bssn\b[^\n]{0,20}\b\d{9}\b/i],
+    ['mrn', /\bMRN\b\s*[:#]?\s*\d{5,}/i],
+    ['dob', /\b(?:DOB|date of birth)\b\s*[:#]?\s*\d/i],
+    ['patient-identifier', /\bpatient\b[^.\n]{0,40}\b(?:name|ssn|mrn|dob|record\s*number)\b/i],
+];
+/**
+ * Scan text for secrets + infra identifiers (always) and PHI (unless
+ * hipaa:false is explicitly passed — PHI is scanned by default).
+ */
+export function scanSensitive(text, opts = {}) {
+    const reasons = [];
+    if (typeof text !== 'string' || text.length === 0)
+        return { flagged: false, reasons };
+    for (const [label, re] of SECRET_PATTERNS)
+        if (re.test(text))
+            reasons.push(label);
+    for (const [label, re] of INFRA_PATTERNS)
+        if (re.test(text))
+            reasons.push('infra:' + label);
+    if (opts.hipaa !== false)
+        for (const [label, re] of PHI_PATTERNS)
+            if (re.test(text))
+                reasons.push('phi:' + label);
+    return { flagged: reasons.length > 0, reasons };
+}

package/dist/templates.d.ts

@@ -36,7 +36,10 @@ export declare function findGeoTierMarker(content: string): {
  *  (reconcile handles that) — we never rewrite a user's prose. */
 export declare function claudeMdIdentity(i: ClanIdentity): string;
 /** Where the brain lives, per tier (matches the fleet's clan-ready layout so
- *  the engine never puts .brain/ where a district/jungle expects its vault). */
+ *  the engine never puts .brain/ where a district/jungle expects its vault).
+ *  An EXISTING vault (i.brainRoot, set from inspect) wins over the tier
+ *  default — applying to a repo with a vault elsewhere must never mint a
+ *  duplicate. */
 export declare function brainRoot(i: ClanIdentity): string;
 export declare function brainScaffold(i: ClanIdentity, today: string): GeneratedFile[];
 /** The command wired into .claude/settings.json SessionStart. Relative (hooks