knosky 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to KnoSky. Versions are git-tagged on this repo.
 
+## [0.5.0] - 2026-07-01 -- Route engine + PR-GPS (Protocol v1)
+
+### Added
+- **`.knosky` protocol foundation:** versioned config (`.knosky/config.yml`), `route.json` and `intent-manifest` schemas (`knosky_protocol: "1.0"`).
+- **Route engine (`kc_route`):** point at a destination -- a file, a folder, an import chain, a "district" (category) -- and get a ranked, advisory route through the repo with waypoints, alternates, confidence, and caveats. Structural only: file/folder/imports/dependency-chain, never semantic/code-meaning.
+- **`kc_bundle`:** builds a shareable intent-manifest (paths + sha256 + edges) with a fail-closed secret scan, for agents that need to share a scoped, verifiable file set.
+- **PR-GPS:** `knosky ci` generates an advisory navigation report for a pull request's changed files. A new GitHub Action posts/updates it as a single PR comment automatically -- advisory only, never blocks or gates a build.
+
+### Security
+- Independent adversarial pass ahead of this release: fixed a symlink-escape read and an unreadable-file fail-open in the bundle engine, a git-ref option-injection in the CI report generator, plus two additional issues found during the pass. See the repo's PR history for detail.
+
+### Notes
+- Everything above is **advisory-only, metadata-only, local, no telemetry** -- KnoSky reads structure, never uploads your code, and nothing here blocks or gates a build.
+
 ## [0.4.1] - 2026-06-29 — Security review fixes
 
 ### Security

package/bin/knosky.mjs

@@ -18,6 +18,45 @@ const flags = new Set(argv.filter(a => a.startsWith('--')));
 const target = path.resolve(argv.find(a => !a.startsWith('--')) || '.');
 const NODE = process.execPath;
 
+// ---------------------------------------------------------------------------
+// ci subcommand: generate PR-GPS advisory artifacts (advisory, never breaks builds)
+// ---------------------------------------------------------------------------
+if (argv.find(a => !a.startsWith('--')) === 'ci') {
+  const { knoskyCi } = await import('../core/ci.mjs');
+
+  // Resolve a named flag's value from argv. Supports --flag=value and --flag value.
+  const getArgVal = (name) => {
+    const prefix = name + '=';
+    const eq = argv.find(a => a.startsWith(prefix));
+    if (eq !== undefined) return eq.slice(prefix.length);
+    const idx = argv.indexOf(name);
+    if (idx !== -1 && idx + 1 < argv.length && !argv[idx + 1].startsWith('--')) {
+      return argv[idx + 1];
+    }
+    return undefined;
+  };
+
+  const ciBase = getArgVal('--base');
+  const ciHead = getArgVal('--head');
+  const ciCity = getArgVal('--city');
+  const ciFailOnSecret = flags.has('--fail-on-secret');
+
+  const { exitCode, summaryMd, routeJson, safetyJson } = await knoskyCi({
+    root: process.cwd(),
+    base: ciBase,
+    head: ciHead,
+    cityPath: ciCity,
+    failOnSecret: ciFailOnSecret,
+  });
+
+  fs.writeFileSync('knosky-pr-summary.md', summaryMd, 'utf8');
+  fs.writeFileSync('knosky-pr-route.json', JSON.stringify(routeJson, null, 2) + '\n', 'utf8');
+  fs.writeFileSync('knosky-safety-report.json', JSON.stringify(safetyJson, null, 2) + '\n', 'utf8');
+
+  console.log(summaryMd);
+  process.exit(exitCode);
+}
+
 if (!fs.existsSync(target)) { console.error('KnoSky: path not found: ' + target); process.exit(1); }
 
 const outDir = path.join(target, '.knosky');

package/core/bundle.mjs

@@ -0,0 +1,172 @@
+// KnoSky bundle engine (KSV2-R4) — intent-manifest builder with fail-closed secret scan.
+// Pure Node stdlib + internal imports only. ESM. No new deps.
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, relative, isAbsolute, sep } from 'node:path';
+import { findSecrets } from './contract.mjs';
+import { makeIntentManifest, validateIntentManifest } from './schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when `ref` is a safe, repo-relative path (not absolute, no "..").
+ * @param {string|undefined} ref
+ * @returns {boolean}
+ */
+function isSafeRef(ref) {
+  if (!ref || typeof ref !== 'string') return false;
+  if (ref.startsWith('/')) return false;
+  // Windows drive: C:\ or C:/
+  if (/^[A-Za-z]:[\\\/]/.test(ref)) return false;
+  if (ref.split(/[/\\]/).some(seg => seg === '..')) return false;
+  return true;
+}
+
+/**
+ * Resolve `ref` under `root` and read it — following symlinks via realpathSync,
+ * then verifying the REAL resolved path still lands inside `root` before the
+ * file is ever opened. `isSafeRef` above only validates the path STRING; it
+ * cannot see that a same-named file on disk is actually a symlink pointing
+ * outside root. This is the actual read boundary (belt-and-suspenders on top
+ * of fs-indexer's own symlink exclusion at index time — this is a separate
+ * read path with its own live filesystem access, so it re-checks independently).
+ *
+ * Never throws. Distinguishes "nothing to scan by design" (no root given —
+ * the caller explicitly opted out of content access) from "root given but the
+ * file could not be verified safe/readable" (fail-closed: caller must treat
+ * this as unscannable, NEVER as clean).
+ *
+ * @param {string|undefined} root
+ * @param {string} ref
+ * @returns {{ buf: Buffer } | { noRoot: true } | { unsafe: true }}
+ */
+function safeRead(root, ref) {
+  if (!root) return { noRoot: true };
+  const full = join(root, ref);
+  let real, rootReal;
+  try {
+    real = realpathSync(full);
+    rootReal = realpathSync(root);
+  } catch {
+    return { unsafe: true }; // missing / broken symlink / permission error — cannot verify
+  }
+  const rel = relative(rootReal, real);
+  if (rel === sep || rel.startsWith('..' + sep) || rel === '..' || isAbsolute(rel)) {
+    return { unsafe: true }; // real path escapes root (symlink pointed outside) — refuse
+  }
+  try {
+    return { buf: readFileSync(real) };
+  } catch {
+    return { unsafe: true };
+  }
+}
+
+/**
+ * Compute the hex SHA-256 of a file. Returns "" when unreadable/unsafe/no-root.
+ * @param {string|undefined} root   Repo root directory, or undefined.
+ * @param {string}           ref    Repo-relative path.
+ * @returns {string}
+ */
+function sha256OfFile(root, ref) {
+  const r = safeRead(root, ref);
+  if (!r.buf) return '';
+  return createHash('sha256').update(r.buf).digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// kcBundle — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an intent-manifest for the given node ids.
+ *
+ * @param {object}   ctx              — retrieve context {city:{nodes}, byId:Map}
+ * @param {string[]} ids              — node ids to include
+ * @param {object}   [opts]
+ * @param {string}   [opts.root]      — repo root; used to read files for sha256 + secret scan
+ * @param {string|null} [opts.expiry] — ISO-8601 expiry timestamp or null
+ * @returns {object} intent-manifest (passes validateIntentManifest)
+ */
+export function kcBundle(ctx, ids, { root, expiry = null } = {}) {
+  // Normalise ids to an array of strings
+  const idList = Array.isArray(ids) ? ids.map(String) : [];
+
+  // Build the set of included ids (only those with safe refs)
+  const includedSet = new Set();
+  const refByid = new Map(); // id -> safe ref string
+
+  for (const id of idList) {
+    const node = ctx.byId.get(id);
+    if (!node) continue; // missing node — skip
+    const ref = node.provenance && node.provenance.ref;
+    if (!isSafeRef(ref)) continue; // absolute or ".." — skip
+    includedSet.add(id);
+    refByid.set(id, ref);
+  }
+
+  // Build paths[] with sha256
+  const paths = [];
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const ref = refByid.get(id);
+    const sha256 = sha256OfFile(root, ref);
+    paths.push({ path: ref, sha256 });
+  }
+
+  // Build edges[] — out-edges within the bundled set
+  const edges = [];
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const node = ctx.byId.get(id);
+    const links = Array.isArray(node.links) ? node.links : [];
+    for (const target of links) {
+      if (includedSet.has(target)) {
+        edges.push({ from: id, to: target });
+      }
+    }
+  }
+
+  // Secret scan — FAIL-CLOSED. Three outcomes per included file:
+  //   noRoot  → caller opted out of content access entirely; nothing to scan by
+  //             design (sha256 is also "" in this mode — a deliberate no-read mode,
+  //             not a failure).
+  //   unsafe  → root WAS given but the file could not be verified safe-and-readable
+  //             (missing, permission error, or a symlink resolving outside root).
+  //             We can no longer prove it's secret-free, so we must NOT call it
+  //             clean — treat it as blocked (the previous behavior silently
+  //             skipped these and returned "clean", a fail-OPEN bug).
+  //   text    → scanned normally.
+  let totalMatches = 0;
+  let blocked = false;
+  let noRootMode = false;
+
+  for (const id of idList) {
+    if (!includedSet.has(id)) continue;
+    const ref = refByid.get(id);
+    const r = safeRead(root, ref);
+    if (r.noRoot) { noRootMode = true; continue; }
+    if (r.unsafe) { blocked = true; continue; }
+    const hits = findSecrets(r.buf.toString('utf8'));
+    if (hits.length > 0) {
+      blocked = true;
+      for (const [, count] of hits) totalMatches += count;
+    }
+  }
+  void noRootMode; // no-root is intentionally a no-op above; named for readability
+
+  const secret_scan = blocked
+    ? { status: 'blocked', count: totalMatches }
+    : { status: 'clean', count: 0 };
+
+  const manifest = makeIntentManifest({ paths, edges, expiry, secret_scan });
+
+  // Invariant: manifest MUST pass validateIntentManifest
+  const validation = validateIntentManifest(manifest);
+  if (!validation.ok) {
+    throw new Error('kcBundle produced an invalid intent-manifest: ' + validation.errors.join('; '));
+  }
+
+  return manifest;
+}

package/core/churn.mjs

@@ -1,11 +1,15 @@
 // Git churn (D-155): per-file commit count (windowed) + last-commit timestamp ONLY.
 // No commit messages, diffs, hunks, authors, or line-level churn retained.
-import { execSync } from 'node:child_process';
+// execFileSync + an args array (not execSync + a shell string) — no argument here is
+// externally controlled today, but this matches the args-array-only discipline used by
+// every other git invocation in this codebase (ci.mjs) and removes the shell entirely,
+// so a future edit that adds a dynamic path/ref here can't reintroduce an injection class.
+import { execFileSync } from 'node:child_process';
 
 export function gitChurn(root) {
   const counts = {}, last = {};
   try {
-    const out = execSync('git log --since=90.days.ago --name-only --pretty=format:%ct -- .', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
+    const out = execFileSync('git', ['log', '--since=90.days.ago', '--name-only', '--pretty=format:%ct', '--', '.'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
     let ts = 0;
     for (const raw of out.split(/\r?\n/)) {
       const line = raw.trim();

package/core/ci.mjs

@@ -0,0 +1,268 @@
+// KnoSky CI artifact generator (KSV2-CI1) — PR-GPS advisory artifact.
+// Pure Node stdlib + node:child_process (git, args-array only) + internal imports.
+// HARD RULE: exit 0 by default. Only --fail-on-secret can cause exit 1, and only
+// when secrets are found in the emitted artifacts. Never throws, never breaks builds.
+import { execFileSync } from 'node:child_process';
+import { load } from './retrieve.mjs';
+import { kcRoute } from './route.mjs';
+import { findSecrets } from './contract.mjs';
+
+// ---------------------------------------------------------------------------
+// Path-safety guard (mirrors the one in route.mjs)
+// ---------------------------------------------------------------------------
+
+function isSafePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.startsWith('/')) return false;
+  if (/^[A-Za-z]:[\\\/]/.test(p)) return false;
+  if (p.split(/[/\\]/).some(seg => seg === '..')) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Git helper — returns changed file list or [] on any error (advisory, never throws)
+// ---------------------------------------------------------------------------
+
+// A conservative git-ref allowlist: SHAs, branch/tag names, and relative refs
+// (HEAD, HEAD~1, HEAD^). Must NOT start with '-' — that's the belt-and-suspenders
+// layer that stops a ref string looking like a CLI flag (e.g. "--output=...")
+// from ever being handed to git, even before --end-of-options runs.
+function isSafeGitRef(ref) {
+  if (!ref || typeof ref !== 'string') return false;
+  if (ref.length > 200) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._/\-~^:]*$/.test(ref);
+}
+
+function gitChangedFiles(root, base, head) {
+  // Refuse to shell out at all if either ref doesn't look like a ref (layer 1).
+  if (!isSafeGitRef(base) || !isSafeGitRef(head)) return [];
+  try {
+    // --end-of-options (layer 2, git >= 2.24) tells git's option parser that
+    // everything after is a revision, never an option — closes the residual
+    // "ref value that happens to start with '-'" injection even though
+    // execFileSync's args-array already rules out shell injection.
+    const output = execFileSync(
+      'git',
+      ['-C', root, 'diff', '--name-only', '--end-of-options', base + '...' + head],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+    return output.split('\n').map(l => l.trim()).filter(Boolean);
+  } catch (_) {
+    // Any git error → advisory empty set, never break the build
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// summaryMd builder
+// ---------------------------------------------------------------------------
+
+function buildSummaryMd(generatedAt, base, head, routes) {
+  const lines = [];
+  lines.push('## KnoSky PR-GPS — Advisory Navigation Report');
+  lines.push('');
+  lines.push('> **ADVISORY ONLY** — metadata pointers only, no file bodies, never blocks the build.');
+  lines.push('');
+  lines.push(`- Generated: ${generatedAt}`);
+  if (base) lines.push(`- Base: \`${base}\``);
+  if (head) lines.push(`- Head: \`${head}\``);
+  lines.push('');
+
+  if (routes.length === 0) {
+    lines.push('_No changed files detected in this PR._');
+  } else {
+    for (const { file, route: routeDoc } of routes) {
+      lines.push(`### \`${file}\``);
+      lines.push('');
+      const topWaypoints = (routeDoc.route || []).slice(0, 5);
+      if (topWaypoints.length === 0) {
+        lines.push('_No route waypoints found in the index for this file._');
+      } else {
+        lines.push('**Route waypoints:**');
+        lines.push('');
+        for (const wp of topWaypoints) {
+          const path = typeof wp === 'string' ? wp : (wp && wp.path) || '';
+          const reason = (wp && wp.reason) || '';
+          lines.push(`- \`${path}\`${reason ? ' — ' + reason : ''}`);
+        }
+      }
+      const confidence = typeof routeDoc.confidence === 'number'
+        ? Math.round(routeDoc.confidence * 100) + '%'
+        : 'n/a';
+      lines.push('');
+      lines.push(`**Confidence:** ${confidence}`);
+      const caveats = (routeDoc.caveats || []).filter(c =>
+        c.includes('recently changed') || c.includes('stale') || c.includes('coverage'),
+      );
+      if (caveats.length > 0) {
+        lines.push('');
+        lines.push('**Caveats:**');
+        for (const c of caveats) lines.push(`- ${c}`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('---');
+  lines.push('_This report is advisory. KnoSky reads metadata only — it does not read code meaning._');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// knoskyCi — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate the KnoSky PR-GPS advisory artifacts.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.root='.']         Repo root for git commands.
+ * @param {string}   [opts.base]             Base ref for git diff.
+ * @param {string}   [opts.head]             Head ref for git diff.
+ * @param {string}   [opts.cityPath]         Path to city-data.json (city index).
+ * @param {boolean}  [opts.failOnSecret=false] Exit 1 only if secrets found in artifacts.
+ * @param {string[]} [opts.changedFiles]     Inject changed files directly (test seam — skips git).
+ * @returns {{ exitCode: number, summaryMd: string, routeJson: object, safetyJson: object }}
+ */
+export async function knoskyCi({
+  root = '.',
+  base,
+  head,
+  cityPath,
+  failOnSecret = false,
+  changedFiles,
+} = {}) {
+  const generatedAt = new Date().toISOString();
+
+  // 1. Resolve changed files
+  let files;
+  if (Array.isArray(changedFiles)) {
+    // Test seam — use injected list directly, no git needed
+    files = changedFiles;
+  } else {
+    // Resolve base/head from args, then environment, then fallback
+    const resolvedBase = base || process.env.GITHUB_BASE_REF || 'HEAD~1';
+    const resolvedHead = head || process.env.GITHUB_SHA || 'HEAD';
+    files = gitChangedFiles(root, resolvedBase, resolvedHead);
+  }
+
+  const resolvedBase = base || process.env.GITHUB_BASE_REF || null;
+  const resolvedHead = head || process.env.GITHUB_SHA || null;
+
+  // 2. Load the city index — if absent/unreadable, produce advisory summary and exit 0
+  let ctx;
+  if (!cityPath) {
+    const summaryMd = buildNoIndexSummary(generatedAt, resolvedBase, resolvedHead);
+    return {
+      exitCode: 0,
+      summaryMd,
+      routeJson: buildRouteJson(generatedAt, resolvedBase, resolvedHead, []),
+      safetyJson: buildSafetyJson(generatedAt, 0),
+    };
+  }
+
+  try {
+    ctx = load(cityPath);
+  } catch (_) {
+    const summaryMd = buildNoIndexSummary(generatedAt, resolvedBase, resolvedHead);
+    return {
+      exitCode: 0,
+      summaryMd,
+      routeJson: buildRouteJson(generatedAt, resolvedBase, resolvedHead, []),
+      safetyJson: buildSafetyJson(generatedAt, 0),
+    };
+  }
+
+  // 3. For each changed file, call kcRoute — metadata only, no file bodies
+  const routes = [];
+  for (const relpath of files) {
+    // Safety: skip any path that escapes the repo
+    if (!isSafePath(relpath)) continue;
+    let routeDoc;
+    try {
+      routeDoc = kcRoute(ctx, 'file:' + relpath);
+    } catch (_) {
+      // Route errors are advisory — skip this file, never break
+      continue;
+    }
+    // Drop any route entries with unsafe paths (defense in depth)
+    if (routeDoc && Array.isArray(routeDoc.route)) {
+      routeDoc.route = routeDoc.route.filter(wp => {
+        const p = typeof wp === 'string' ? wp : (wp && wp.path);
+        return !p || isSafePath(p);
+      });
+    }
+    if (routeDoc && Array.isArray(routeDoc.alternates)) {
+      routeDoc.alternates = routeDoc.alternates.filter(wp => {
+        const p = typeof wp === 'string' ? wp : (wp && wp.path);
+        return !p || isSafePath(p);
+      });
+    }
+    routes.push({ file: relpath, route: routeDoc });
+  }
+
+  // 4. Build routeJson
+  const routeJson = buildRouteJson(generatedAt, resolvedBase, resolvedHead, routes);
+
+  // 5. Build summaryMd
+  const summaryMd = buildSummaryMd(generatedAt, resolvedBase, resolvedHead, routes);
+
+  // 6. Scan ONLY the emitted artifacts for secrets (defense in depth)
+  const artifactText = summaryMd + '\n' + JSON.stringify(routeJson);
+  const secretHits = findSecrets(artifactText);
+  const secretsFound = secretHits.reduce((n, [, count]) => n + count, 0);
+
+  // 7. Build safetyJson
+  const safetyJson = buildSafetyJson(generatedAt, secretsFound);
+
+  // 8. exitCode: only failOnSecret+secrets_found > 0 can be non-zero
+  const exitCode = (failOnSecret && secretsFound > 0) ? 1 : 0;
+
+  return { exitCode, summaryMd, routeJson, safetyJson };
+}
+
+// ---------------------------------------------------------------------------
+// Artifact builders
+// ---------------------------------------------------------------------------
+
+function buildNoIndexSummary(generatedAt, base, head) {
+  const lines = [
+    '## KnoSky PR-GPS — Advisory Navigation Report',
+    '',
+    '> **ADVISORY ONLY** — metadata pointers only, no file bodies, never blocks the build.',
+    '',
+    `- Generated: ${generatedAt}`,
+  ];
+  if (base) lines.push(`- Base: \`${base}\``);
+  if (head) lines.push(`- Head: \`${head}\``);
+  lines.push('');
+  lines.push('_No index available — run `knosky <path>` to build the city index first._');
+  lines.push('');
+  lines.push('---');
+  lines.push('_This report is advisory. KnoSky reads metadata only._');
+  return lines.join('\n');
+}
+
+function buildRouteJson(generatedAt, base, head, routes) {
+  return {
+    knosky_protocol: '1.0',
+    artifact_type: 'pr-route',
+    advisory: true,
+    generated_at: generatedAt,
+    base: base || null,
+    head: head || null,
+    routes: routes.map(({ file, route }) => ({ file, route })),
+  };
+}
+
+function buildSafetyJson(generatedAt, secretsFound) {
+  return {
+    knosky_protocol: '1.0',
+    artifact_type: 'safety-report',
+    advisory: true,
+    generated_at: generatedAt,
+    absolute_paths: false,
+    secrets_found: secretsFound,
+    redaction: 'metadata-only; no file bodies; no absolute paths',
+  };
+}