@descix/cli 1.0.0 → 1.0.3

package/lib/commands/briefer/sources/environments.js

@@ -0,0 +1,205 @@
+/**
+ * §2 — Environments extractor (M2 implementation).
+ *
+ * Per WS-DESCIX-BRIEFER-CLI scope doc §2.2 §2, this extractor reads:
+ *   - DEV/DEMO/PROD parallelism — architectural fact distilled from
+ *     V2_docs/architecture/platform-runtime-mental-model.md (cite the doc).
+ *   - ENV_CONFIG block from provision-platform-lb.js:32-47.
+ *   - DEPLOY_ENV-bound-once hard-fail from descix-cloud-core/src/config.js
+ *     (locate dynamically; canonical briefer line range is allowed to drift).
+ *   - Secret Manager config name pattern from DeSciX_Cloud/CLAUDE.md (cite the
+ *     doc since the values are env-keyed and live in env-vars/secrets, not
+ *     code) — locate the "Secret Manager — Per-Environment Isolation" table.
+ *
+ * Optional gcloud verification: list Cloud Function names matching `apiFront-http`
+ * and Firestore database names matching `descix-{env}` / `descix`.
+ */
+import {
+  readSourceFile,
+  findInLines,
+  makeCitation,
+  sliceRange,
+  probeGcloudJson
+} from '../util/source-reader.js';
+import { BrieferExtractorError, BRIEFER_ERROR_CODES } from '../errors.js';
+
+export const SECTION = {
+  number: 2,
+  heading: '2. Environments',
+  sourceFiles: [
+    'DeSciX/V2_docs/architecture/platform-runtime-mental-model.md',
+    'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js',
+    'DeSciX/DeSciX_Core/descix-cloud-core/src/config.js',
+    'DeSciX/DeSciX_Cloud/CLAUDE.md'
+  ]
+};
+
+const RUNTIME_MM = 'DeSciX/V2_docs/architecture/platform-runtime-mental-model.md';
+const MESH_FILE = 'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js';
+const CONFIG_FILE = 'DeSciX/DeSciX_Core/descix-cloud-core/src/config.js';
+const CLOUD_CLAUDE = 'DeSciX/DeSciX_Cloud/CLAUDE.md';
+
+export async function extract({ env, cliPaths } = {}) {
+  if (!env) {
+    throw new BrieferExtractorError({
+      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      source: 'extractor argument',
+      expected: 'env (dev|demo|prod) provided by caller',
+      recovery: 'Pass {env} from the briefer entry point.'
+    });
+  }
+  if (!cliPaths) {
+    throw new BrieferExtractorError({
+      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      source: 'extractor argument',
+      expected: 'cliPaths provided by caller',
+      recovery: 'Pass {cliPaths} from the briefer entry point.'
+    });
+  }
+
+  // ── Source 1: ENV_CONFIG in provision-platform-lb.js ──
+  const mesh = await readSourceFile({
+    cliPaths,
+    relPath: MESH_FILE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+  const envConfigMatch = findInLines({
+    lines: mesh.lines,
+    regex: /const\s+ENV_CONFIG\s*=\s*\{/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${MESH_FILE} (ENV_CONFIG)`,
+    expected: 'const ENV_CONFIG = { prod: {...}, demo: {...}, dev: {...} }',
+    recovery: `Re-locate the ENV_CONFIG construct in ${MESH_FILE}.`,
+    expectedRange: [20, 60]
+  });
+  const envConfigEnd = findObjectEnd(mesh.lines, envConfigMatch.lineNumber);
+  const envConfigBlock = sliceRange(mesh.lines, envConfigMatch.lineNumber, envConfigEnd);
+
+  // ── Source 2: config.js — DEPLOY_ENV-bound-once hard-fail ──
+  const config = await readSourceFile({
+    cliPaths,
+    relPath: CONFIG_FILE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+  const deployEnvBoundMatch = findInLines({
+    lines: config.lines,
+    regex: /FATAL:\s*DEPLOY_ENV\s+not\s+set/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${CONFIG_FILE} (DEPLOY_ENV bound-once hard-fail)`,
+    expected: 'throw with message starting "[CloudConfig] FATAL: DEPLOY_ENV not set"',
+    recovery: `Re-locate the DEPLOY_ENV hard-fail in ${CONFIG_FILE}.`
+  });
+
+  // ── Source 3: runtime-mental-model.md doc cite (distilled architectural fact) ──
+  // We just verify the doc exists + record SHA of the canonical range. The doc
+  // is the source for "DEV/DEMO/PROD are fully parallel" because that's an
+  // assertion spread across many code paths — too noisy to grep.
+  const rmm = await readSourceFile({
+    cliPaths,
+    relPath: RUNTIME_MM,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+
+  // ── Source 4: Cloud CLAUDE.md Secret Manager table ──
+  const claude = await readSourceFile({
+    cliPaths,
+    relPath: CLOUD_CLAUDE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+  const secretTableMatch = findInLines({
+    lines: claude.lines,
+    regex: /descix_config_demo/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${CLOUD_CLAUDE} (Secret Manager Per-Environment Isolation table)`,
+    expected: 'descix_config_demo row in the per-env secret table',
+    recovery: `Re-locate the Secret Manager isolation table in ${CLOUD_CLAUDE}.`
+  });
+
+  // ── M3: live gcloud probes (HARD-FAIL on demo/prod, skipped on dev) ──
+  const probeCitations = [];
+  let gcloudCfNote = '';
+  let gcloudFsNote = '';
+
+  if (env === 'dev') {
+    // DEV is local. Probe is intentionally skipped; emit a stanza so the
+    // operator knows live state was not verified for this regen.
+    gcloudCfNote = '\n_DEV: gcloud probes skipped (local dev environment — no Cloud Functions or Firestore to probe)._\n';
+  } else {
+    const cfProbe = await probeGcloudJson({
+      command: ['functions', 'list', '--v2', '--format=json'],
+      env,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      anchor: 'cloud-functions-list',
+      expected: 'JSON array of gen2 Cloud Functions for project descix',
+      recovery: `Run 'gcloud auth login' and 'gcloud config set project descix'. The Cloud Functions list cross-check is required for env=${env}.`
+    });
+    const apiFrontCfs = (cfProbe.json || [])
+      .filter(f => /apiFront-http/.test(f.name || ''))
+      .map(f => (f.name || '').split('/').pop());
+    gcloudCfNote = `\n_Live Cloud Functions matching \`apiFront-http\` (probed \`${cfProbe.citation.probe}\`, env=\`${env}\`):_ ${apiFrontCfs.length > 0 ? apiFrontCfs.map(n => '\`' + n + '\`').join(', ') : '_(none found)_'}\n`;
+    probeCitations.push(cfProbe.citation);
+
+    const fsProbe = await probeGcloudJson({
+      command: ['firestore', 'databases', 'list', '--format=json'],
+      env,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      anchor: 'firestore-databases-list',
+      expected: 'JSON array of Firestore databases for project descix',
+      recovery: `Run 'gcloud auth login' and 'gcloud config set project descix'. The Firestore databases cross-check is required for env=${env}.`
+    });
+    const dbs = (fsProbe.json || [])
+      .map(d => (d.name || '').split('/').pop())
+      .filter(n => /^descix/.test(n));
+    gcloudFsNote = `\n_Live Firestore databases matching \`descix*\` (probed \`${fsProbe.citation.probe}\`, env=\`${env}\`):_ ${dbs.length > 0 ? dbs.map(n => '\`' + n + '\`').join(', ') : '_(none found)_'}\n`;
+    probeCitations.push(fsProbe.citation);
+  }
+
+  // ── Render markdown ──
+  const markdown = [
+    `DEV / DEMO / PROD are **fully parallel cloud deployments.** They co-exist; PROD does not replace DEMO. — \`${RUNTIME_MM}\``,
+    ``,
+    `Per env, isolated:`,
+    `- Cloud Function: \`apiFront-http-{env}\` (and \`apiFront-http\` for PROD)`,
+    `- Firestore DB: \`descix-{env}\` (and \`descix\` for PROD)`,
+    `- Secret Manager config: \`descix_config_{env}\` (DEV/DEMO) or \`descix_config\` with version aliases (PROD/PREVIEW) — \`${CLOUD_CLAUDE}:${secretTableMatch.lineNumber}\``,
+    `- GCS bucket prefix: \`{env}/\``,
+    `- LB host suffix: \`.{env}.descix.net\` for DEV/DEMO, \`.descix.net\` for PROD`,
+    ``,
+    `ENV_CONFIG (the deploy-time env table — \`${MESH_FILE}:${envConfigMatch.lineNumber}-${envConfigEnd}\`):`,
+    ``,
+    '```js',
+    envConfigBlock,
+    '```',
+    ``,
+    `One process serves exactly one env, determined by \`DEPLOY_ENV\`. The cloud-core bootstrap **hard-fails** at construct time if \`DEPLOY_ENV\` is unset — there is no default. — \`${CONFIG_FILE}:${deployEnvBoundMatch.lineNumber}\``,
+    gcloudCfNote,
+    gcloudFsNote
+  ].join('\n');
+
+  const citations = [
+    makeCitation({ file: MESH_FILE, lines: `${envConfigMatch.lineNumber}-${envConfigEnd}`, anchor: 'ENV_CONFIG', fileLines: mesh.lines }),
+    makeCitation({ file: CONFIG_FILE, lines: String(deployEnvBoundMatch.lineNumber), anchor: 'DEPLOY_ENV bound-once', fileLines: config.lines }),
+    makeCitation({ file: RUNTIME_MM, lines: `1-${rmm.lines.length}`, anchor: 'DEV/DEMO/PROD parallelism', fileLines: rmm.lines }),
+    makeCitation({ file: CLOUD_CLAUDE, lines: String(secretTableMatch.lineNumber), anchor: 'Secret Manager per-env isolation', fileLines: claude.lines }),
+    ...probeCitations
+  ];
+
+  return { markdown, citations };
+}
+
+function findObjectEnd(lines, startLine) {
+  const MAX = Math.min(lines.length, startLine + 50);
+  let depth = 0;
+  for (let i = startLine - 1; i < MAX; i++) {
+    for (const ch of lines[i]) {
+      if (ch === '{') depth++;
+      else if (ch === '}') {
+        depth--;
+        if (depth === 0) return i + 1;
+      }
+    }
+  }
+  return Math.min(lines.length, startLine + 30);
+}

package/lib/commands/briefer/sources/identifiers.js

@@ -0,0 +1,214 @@
+/**
+ * §1 — Identifiers & invariants extractor (M2 implementation).
+ *
+ * Per WS-DESCIX-BRIEFER-CLI scope doc §2.2 §1, this extractor reads:
+ *   - Domain pattern from provision-platform-lb.js:120 (host construction)
+ *   - GCS path pattern from provision-platform-lb.js:123 (pathPrefix)
+ *   - product_id === app_id invariant from hydrateUtils.js
+ *   - Agentic-app / communities-as-apps invariant from the BEAST CEO record
+ *     `apps/unk-beast/kb/Org/agentic-app-invariant-2026-05-26.jsonl`
+ *   - the AI (model, thinking) precedence chain from geminiInteractions.js::resolveModelThinkingPair()
+ *
+ * Extraction method: regex+checksum-of-surrounding-lines (NOT AST).
+ * Per scope §9.1 third-order question, decision documented 2026-05-26: regex
+ * keeps the CLI dep-light; AST may be added per-extractor later if needed.
+ *
+ * HARD-FAIL behavior:
+ *   - Missing source file → BRIEFER-SRC-NOT-FOUND
+ *   - Regex pattern doesn't match → BRIEFER-SRC-NOT-FOUND
+ *   - Pattern matches outside expected line range → BRIEFER-PARSE-FAIL
+ *   - BEAST agentic-app record missing → BRIEFER-SRC-NOT-FOUND (a hard
+ *     invariant — this is the CEO-broadcast canonical record)
+ */
+import {
+  readSourceFile,
+  findInLines,
+  makeCitation,
+  sliceRange
+} from '../util/source-reader.js';
+import { BrieferExtractorError, BRIEFER_ERROR_CODES } from '../errors.js';
+// The (model, thinking) precedence chain in words, from its ONE owner. The briefer
+// QUOTES the served contract rather than paraphrasing it — a briefer paraphrase of a
+// chain is exactly how the old five-step list outlived the code it described.
+import { MODEL_THINKING_CHAIN } from '@descix/platform-api/mcp-tools';
+
+export const SECTION = {
+  number: 1,
+  heading: '1. Identifiers & invariants',
+  sourceFiles: [
+    'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js',
+    'DeSciX/DeSciX_Core/descix-platform-api/src/entitlements/index.js',
+    'DeSciX/DeSciX_Cloud/microservice/services/geminiInteractions.js',
+    'apps/unk-beast/kb/Org/agentic-app-invariant-2026-05-26.jsonl'
+  ]
+};
+
+const MESH_FILE = 'DeSciX/DeSciX_Cloud/microservice/admin/scripts/deploy/provision-platform-lb.js';
+const HYDRATE_FILE = 'DeSciX/DeSciX_Core/descix-platform-api/src/entitlements/index.js';
+const GEMINI_FILE = 'DeSciX/DeSciX_Cloud/microservice/services/geminiInteractions.js';
+const AGENTIC_RECORD = 'apps/unk-beast/kb/Org/agentic-app-invariant-2026-05-26.jsonl';
+
+export async function extract({ env, cliPaths } = {}) {
+  if (!env) {
+    throw new BrieferExtractorError({
+      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      source: 'extractor argument',
+      expected: 'env (dev|demo|prod) provided by caller',
+      recovery: 'Pass {env} from the briefer entry point.'
+    });
+  }
+  if (!cliPaths) {
+    throw new BrieferExtractorError({
+      code: BRIEFER_ERROR_CODES.NOT_IMPLEMENTED,
+      section: `§${SECTION.number} ${SECTION.heading}`,
+      source: 'extractor argument',
+      expected: 'cliPaths provided by caller',
+      recovery: 'Pass {cliPaths} from the briefer entry point.'
+    });
+  }
+
+  // ── Source 1: provision-platform-lb.js — domain + gcsPath patterns ──
+  const mesh = await readSourceFile({
+    cliPaths,
+    relPath: MESH_FILE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+
+  // Host pattern: canonical line shifted to L214 after WS-DESCIX-SINGLETON-PROVISIONER
+  // (CEO-D-2026-05-26-SINGLETON-PROVISIONER-UNIFIED, 2026-05-26) added the
+  // SINGLETON_APPS branch + buildSingletonMatcher helper near top of file. The
+  // line is the canonical UNIFORM host formula (which a singleton override then
+  // shadows via `effectiveHost` for daita) — briefer extractor still keys on
+  // this exact construct as the platform routing invariant. Range expanded to
+  // 100-350 to tolerate NEG helpers + matcher builders in provision-platform-lb.js.
+  const hostMatch = findInLines({
+    lines: mesh.lines,
+    regex: /const\s+host\s*=\s*env\s*===\s*['"]prod['"]\s*\?/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${MESH_FILE}:214 (uniform host pattern; CEO-D-2026-05-26-LB-ROUTING-UNIFORM)`,
+    expected: `const host = env === 'prod' ? ... : ... construct`,
+    recovery: `Re-locate the host construct in ${MESH_FILE} and update sources/identifiers.js.`,
+    expectedRange: [100, 350]
+  });
+
+  // gcsPath pattern: canonical line shifted to L223 after WS-DESCIX-SINGLETON-PROVISIONER.
+  // This is the non-singleton (uniform) pathPrefix; the singleton override
+  // (pathPrefixSingletonOverride) is a few lines below. Range matches hostMatch.
+  const gcsMatch = findInLines({
+    lines: mesh.lines,
+    regex: /const\s+pathPrefix\s*=\s*`\/\$\{env\}\/\$\{app\}\/site`/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${MESH_FILE}:223 (uniform gcsPath pattern; singleton override at ~L228)`,
+    expected: 'const pathPrefix = `/${env}/${app}/site` (template literal)',
+    recovery: `Re-locate the gcsPath construct in ${MESH_FILE}.`,
+    expectedRange: [100, 350]
+  });
+
+  // ── Source 2: hydrateUtils.js — product_id===app_id invariant ──
+  const hydrate = await readSourceFile({
+    cliPaths,
+    relPath: HYDRATE_FILE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+
+  const hydrateMatch = findInLines({
+    lines: hydrate.lines,
+    regex: /hydrateCommunityIdFromProducts/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${HYDRATE_FILE} (hydrateCommunityIdFromProducts definition)`,
+    expected: 'hydrateCommunityIdFromProducts function declaration',
+    recovery: `Verify hydrateCommunityIdFromProducts is still exported from ${HYDRATE_FILE}.`
+  });
+
+  // ── Source 3: geminiInteractions.js — the (model, thinking) pair owner ──
+  const gemini = await readSourceFile({
+    cliPaths,
+    relPath: GEMINI_FILE,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+
+  const resolverMatch = findInLines({
+    lines: gemini.lines,
+    regex: /export\s+function\s+resolveModelThinkingPair\b/,
+    section: `§${SECTION.number} ${SECTION.heading}`,
+    source: `${GEMINI_FILE} (resolveModelThinkingPair)`,
+    expected: 'export function resolveModelThinkingPair(...)',
+    recovery: `resolveModelThinkingPair has been moved or renamed. Re-locate and update the extractor.`
+  });
+  // Capture the resolver body — from the export to the next closing brace at
+  // column 0. We'll scan forward a bounded window and slice for the briefer.
+  const resolverEnd = findResolverEnd(gemini.lines, resolverMatch.lineNumber);
+  const resolverBody = sliceRange(gemini.lines, resolverMatch.lineNumber, resolverEnd);
+
+  // ── Source 4: BEAST CEO record — agentic-app invariant ──
+  const beast = await readSourceFile({
+    cliPaths,
+    relPath: AGENTIC_RECORD,
+    section: `§${SECTION.number} ${SECTION.heading}`
+  });
+  // The record is JSONL; the canonical claim is one of the question/answer
+  // chunks. We don't parse the JSONL — we just verify the record EXISTS and
+  // SHA the whole file for citation purposes. The CEO broadcast title is the
+  // contract; the briefer prose embeds it verbatim.
+  const beastSha = makeCitation({
+    file: AGENTIC_RECORD,
+    lines: `1-${beast.lines.length}`,
+    anchor: 'AGENTIC-APP-INHERITANCE-INVARIANT-2026-05-26',
+    fileLines: beast.lines
+  }).sha;
+
+  // ── Render the briefer markdown ──
+  const hostLine = mesh.lines[hostMatch.lineNumber - 1].trim();
+  const gcsLine = mesh.lines[gcsMatch.lineNumber - 1].trim();
+
+  const markdown = [
+    `- **Apps are the central unit. Everything is an agentic app.** Communities are themselves agentic apps that share IP with other apps in the same community. The platform is fundamentally an agentic-app store, not a generic SaaS platform with apps bolted on. — \`${AGENTIC_RECORD}\` (CEO broadcast \`AGENTIC-APP-INHERITANCE-INVARIANT-2026-05-26\`, sha=\`${beastSha}\`)`,
+    `- \`app_id\` is a globally unique slug (e.g., \`daita\`, \`powch\`, \`egpt\`). Same value across DEV, DEMO, PROD. Never contains the environment.`,
+    `- \`community_id\` is operational metadata stored INSIDE \`Products/{app_id}\`. Never parsed from URL. Never trusted from client.`,
+    `- \`product_id === app_id\` — the same opaque slug. Server re-derives \`community_id\` from \`Products/{app_id}\` via \`hydrateCommunityIdFromProducts()\`. — \`${HYDRATE_FILE}:${hydrateMatch.lineNumber}\``,
+    `- Domain pattern: \`{app_id}.{env}.descix.net\` for DEV/DEMO; \`{app_id}.descix.net\` for PROD. — \`${MESH_FILE}:${hostMatch.lineNumber}\``,
+    '  ```js',
+    `  ${hostLine}`,
+    '  ```',
+    `- GCS path: \`{env}/{app_id}/site/\`. Flat — no community in the path. — \`${MESH_FILE}:${gcsMatch.lineNumber}\``,
+    '  ```js',
+    `  ${gcsLine}`,
+    '  ```',
+    `- Wildcard TLS cert: \`*.descix.net\` plus per-env wildcards. ONE cert. No per-app cert provisioning.`,
+    `- **AI (model, thinking) precedence.** ${MODEL_THINKING_CHAIN} Owner: \`resolveModelThinkingPair()\` in \`${GEMINI_FILE}:${resolverMatch.lineNumber}\` — the ONE resolver; the model chain and the thinking chain used to be separate and could assemble a pair no config declared.`,
+    '  ```js',
+    indentBlock(resolverBody, '  '),
+    '  ```'
+  ].join('\n');
+
+  const citations = [
+    makeCitation({ file: MESH_FILE, lines: String(hostMatch.lineNumber), anchor: 'host pattern', fileLines: mesh.lines }),
+    makeCitation({ file: MESH_FILE, lines: String(gcsMatch.lineNumber), anchor: 'gcsPath pattern', fileLines: mesh.lines }),
+    makeCitation({ file: HYDRATE_FILE, lines: String(hydrateMatch.lineNumber), anchor: 'hydrateCommunityIdFromProducts', fileLines: hydrate.lines }),
+    makeCitation({ file: GEMINI_FILE, lines: `${resolverMatch.lineNumber}-${resolverEnd}`, anchor: 'resolveModelThinkingPair', fileLines: gemini.lines }),
+    { file: AGENTIC_RECORD, lines: `1-${beast.lines.length}`, anchor: 'AGENTIC-APP-INHERITANCE-INVARIANT-2026-05-26', sha: beastSha }
+  ];
+
+  return { markdown, citations };
+}
+
+/**
+ * Walk forward from the `export function resolveModelThinkingPair` line until we hit
+ * a closing brace at column 0. Bounded scan window of 80 lines so a runaway
+ * regex on a refactored file doesn't drag the whole file into the briefer.
+ */
+function findResolverEnd(lines, startLine) {
+  const MAX = Math.min(lines.length, startLine + 80);
+  for (let i = startLine; i < MAX; i++) {
+    if (lines[i] === '}') return i + 1;
+  }
+  // If we don't find a clean close, fall back to startLine+30 — we want some
+  // body in the briefer even if the resolver was reformatted; --check will
+  // catch the SHA change.
+  return Math.min(lines.length, startLine + 30);
+}
+
+function indentBlock(block, indent) {
+  return block.split('\n').map(l => indent + l).join('\n');
+}