snipara-companion 2.0.7 → 2.0.8

package/README.md

@@ -99,4 +99,7 @@ The previous long README has moved to [docs/FULL_REFERENCE.md](./docs/FULL_REFER
 Start there for the full command list, hook setup, hosted MCP bridge commands,
 workflow modes, team-sync, local context packs, and release-oriented flows.
 
+Launch assets, demo scripts, and post drafts live in
+[docs/launch/LAUNCH_KIT.md](./docs/launch/LAUNCH_KIT.md).
+
 Release notes live in [CHANGELOG.md](./CHANGELOG.md).

package/dist/index.d.ts

@@ -1532,9 +1532,16 @@ interface LocalCodeOverlayImport {
     specifier: string;
     line: number;
 }
+interface LocalCodeOverlayWarning {
+    code: string;
+    severity: "info" | "warning";
+    message: string;
+    [key: string]: unknown;
+}
 interface LocalCodeOverlayExcludedFile {
     path: string;
     reason: "ignored" | "unsupported_language" | "too_large" | "secret_pattern" | "read_error";
+    line?: number;
 }
 interface LocalCodeOverlayManifest {
     version: "snipara.local_code_overlay.v1";
@@ -1560,11 +1567,7 @@ interface LocalCodeOverlayManifest {
         byReason: Record<LocalCodeOverlayExcludedFile["reason"], number>;
         samples: LocalCodeOverlayExcludedFile[];
     };
-    warnings: Array<{
-        code: string;
-        severity: "info" | "warning";
-        message: string;
-    }>;
+    warnings: LocalCodeOverlayWarning[];
 }
 interface CodeStatusCommandOptions {
     dir?: string;

package/dist/index.js

@@ -3055,19 +3055,63 @@ function isIgnored(filePath, sniparaIgnore) {
   }
   return sniparaIgnore.some((pattern) => matchesIgnorePattern(normalized, pattern));
 }
-function hasSecretPattern2(content) {
-  if (SECRET_PATTERNS.some((pattern) => pattern.test(content))) {
-    return true;
+function findUnsafeSecretAssignment(line) {
+  const match = line.match(SECRET_ASSIGNMENT_PATTERN);
+  if (!match) {
+    return null;
   }
-  return content.split(/\r?\n/).some((line) => {
-    const match = line.match(SECRET_ASSIGNMENT_PATTERN);
-    if (!match) {
-      return false;
-    }
-    const value = match[1] ?? match[2] ?? match[3] ?? "";
-    const normalized = value.trim().toLowerCase();
-    return !SAFE_SECRET_VALUE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+  const value = match[1] ?? match[2] ?? match[3] ?? "";
+  const normalized = value.trim().toLowerCase();
+  if (SAFE_SECRET_VALUE_PREFIXES.some((prefix) => normalized.startsWith(prefix))) {
+    return null;
+  }
+  return { value };
+}
+function redactSecretLikeContentForOverlay(content) {
+  const findings = [];
+  const lines = content.split(/\r?\n/);
+  const redactedLines = lines.map((line, index) => {
+    const lineNumber = index + 1;
+    if (SECRET_PATTERNS.some((pattern) => pattern.test(line))) {
+      findings.push({ line: lineNumber, reason: "private_key" });
+      return "[SNIPARA_REDACTED_SECRET_LIKE_LINE]";
+    }
+    const assignment = findUnsafeSecretAssignment(line);
+    if (!assignment) {
+      return line;
+    }
+    findings.push({ line: lineNumber, reason: "secret_assignment" });
+    return line.replace(assignment.value, "[SNIPARA_REDACTED_SECRET]");
   });
+  return {
+    content: redactedLines.join("\n"),
+    findings
+  };
+}
+function formatSecretWarningMessage(samples) {
+  const displayed = samples.slice(0, 5).map((sample) => {
+    const lines = sample.lines.slice(0, 5).join(",");
+    const suffix = sample.lines.length > 5 ? ",..." : "";
+    return `${sample.path}:${lines}${suffix}`;
+  });
+  const more = samples.length > displayed.length ? `; ${samples.length - displayed.length} more` : "";
+  return `Secret-like lines were redacted before local graph extraction; files remain visible to impact. Samples: ${displayed.join("; ")}${more}.`;
+}
+function toSecretWarningSamples(samples) {
+  return samples.map((sample) => ({
+    path: sample.path,
+    lines: sample.findings.map((finding) => finding.line),
+    reasons: [...new Set(sample.findings.map((finding) => finding.reason))]
+  }));
+}
+function formatSecretRedactionWarning(samples) {
+  const warningSamples = toSecretWarningSamples(samples);
+  return {
+    code: "secret_like_lines_redacted",
+    severity: "warning",
+    message: formatSecretWarningMessage(warningSamples),
+    samples: warningSamples
+  };
 }
 function listWorkingTreeFiles(repoRoot) {
   const files = splitNul(runGitBuffer(["ls-files", "-co", "--exclude-standard", "-z"], repoRoot));
@@ -3229,6 +3273,7 @@ function buildLocalCodeOverlay(options = {}) {
   const symbols = [];
   const imports = [];
   const excludedSamples = [];
+  const secretRedactionSamples = [];
   const byReason = {
     ignored: 0,
     unsupported_language: 0,
@@ -3271,16 +3316,17 @@ function buildLocalCodeOverlay(options = {}) {
       continue;
     }
     const content = contentBuffer.toString("utf8");
-    if (hasSecretPattern2(content)) {
-      addExcluded(filePath, "secret_pattern");
-      continue;
+    const redaction = redactSecretLikeContentForOverlay(content);
+    const indexedContent = redaction.content;
+    if (redaction.findings.length > 0) {
+      secretRedactionSamples.push({ path: filePath, findings: redaction.findings });
     }
-    const extracted = extractCode(content, filePath, language);
+    const extracted = extractCode(indexedContent, filePath, language);
     files.push({
       path: filePath,
       language,
       sizeBytes: contentBuffer.length,
-      sha256: sha2563(contentBuffer),
+      sha256: sha2563(indexedContent),
       symbolCount: extracted.symbols.length,
       importCount: extracted.imports.length
     });
@@ -3300,12 +3346,8 @@ function buildLocalCodeOverlay(options = {}) {
       message: "The working tree is dirty, but this overlay was built from the selected commit only."
     });
   }
-  if (byReason.secret_pattern > 0) {
-    warnings.push({
-      code: "secret_like_files_excluded",
-      severity: "warning",
-      message: "One or more supported code files were excluded because they matched secret patterns."
-    });
+  if (secretRedactionSamples.length > 0) {
+    warnings.push(formatSecretRedactionWarning(secretRedactionSamples));
   }
   const dirtyTreeHash = mode === "working_tree" && dirtyStatus.trim() ? shortHash(
     JSON.stringify({
@@ -3499,6 +3541,86 @@ function buildLocalFileEdges(manifest) {
     return target ? [{ from: item.filePath, to: target, specifier: item.specifier, line: item.line }] : [];
   });
 }
+function missingTargetDetail(manifest, filePath) {
+  const excluded = manifest.excluded.samples.find((sample) => sample.path === filePath);
+  if (!excluded) {
+    const hitFileLimit = manifest.warnings.some(
+      (warning) => warning.code === "local_overlay_file_limit_reached"
+    );
+    return {
+      path: filePath,
+      reason: "not_in_overlay",
+      remediation: hitFileLimit ? "The overlay reached --max-files before this target was indexed. Increase --max-files and rebuild without --cached." : "Rebuild without --cached, then check the path, .sniparaignore, supported language, or generated-file state."
+    };
+  }
+  const remediationByReason = {
+    ignored: "Remove or narrow the matching .sniparaignore/default ignore rule if this file should be indexed.",
+    unsupported_language: "Local overlay impact currently indexes TypeScript, TSX, Python, and Go files.",
+    too_large: "This file is above the local overlay size limit. Split the generated file or raise maxFileBytes in the local overlay builder.",
+    secret_pattern: "Rebuild without --cached so secret-like lines can be redacted and the file can stay in the graph; inspect the reported line if it should be changed.",
+    read_error: "The file could not be read from the selected working tree or commit."
+  };
+  return {
+    path: filePath,
+    reason: excluded.reason,
+    ...excluded.line ? { line: excluded.line } : {},
+    remediation: remediationByReason[excluded.reason]
+  };
+}
+function buildMissingTargetsWarning(manifest, missingTargetFiles) {
+  if (missingTargetFiles.length === 0) {
+    return null;
+  }
+  const details = missingTargetFiles.map((filePath) => missingTargetDetail(manifest, filePath));
+  const reasons = [...new Set(details.map((detail) => String(detail.reason)))];
+  const remediation = [...new Set(details.map((detail) => String(detail.remediation)))].join(" ");
+  return {
+    code: "local_impact_targets_missing",
+    severity: "warning",
+    message: "One or more requested impact targets are not present in the selected local overlay. " + remediation,
+    files: missingTargetFiles,
+    reasons,
+    details
+  };
+}
+function parseSecretWarningSamples(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    if (!item || typeof item !== "object") {
+      return [];
+    }
+    const record = item;
+    const pathValue = typeof record.path === "string" ? record.path : void 0;
+    const lines = Array.isArray(record.lines) ? record.lines.filter((line) => typeof line === "number") : [];
+    const reasons = Array.isArray(record.reasons) ? record.reasons.filter((reason) => typeof reason === "string") : [];
+    return pathValue && lines.length > 0 ? [{ path: pathValue, lines, reasons }] : [];
+  });
+}
+function impactOverlayWarnings(warnings, relevantFiles) {
+  return warnings.flatMap((warning) => {
+    if (warning.code === "local_overlay_file_limit_reached") {
+      return [warning];
+    }
+    if (warning.code !== "secret_like_lines_redacted") {
+      return [];
+    }
+    const samples = parseSecretWarningSamples(warning.samples).filter(
+      (sample) => relevantFiles.has(sample.path)
+    );
+    if (samples.length === 0) {
+      return [];
+    }
+    return [
+      {
+        ...warning,
+        message: formatSecretWarningMessage(samples),
+        samples
+      }
+    ];
+  });
+}
 function printLocalQueryResult(result, json) {
   if (json) {
     console.log(JSON.stringify(result, null, 2));
@@ -3725,6 +3847,7 @@ function printLocalImpactHumanResult(result) {
   const outgoing = uniqueEdgeFiles(impact.outgoing, "to");
   const warnings = Array.isArray(impact.warnings) ? impact.warnings : [];
   const missingTargets = Array.isArray(impact.missingTargetFiles) ? impact.missingTargetFiles.filter((item) => typeof item === "string") : [];
+  const missingTargetDetails = extractMissingTargetDetails(impact.missingTargetDetails);
   console.log(import_chalk.default.bold(`Code impact - local - ${target}`));
   console.log(`Source: ${result.sourceSelection.selected}`);
   console.log(`Reason: ${result.sourceSelection.reason}`);
@@ -3736,7 +3859,8 @@ function printLocalImpactHumanResult(result) {
     console.log("");
     console.log(import_chalk.default.yellow(`Missing targets (${missingTargets.length})`));
     for (const filePath of missingTargets.slice(0, 12)) {
-      console.log(`  ${filePath}`);
+      const detail = missingTargetDetails.get(filePath);
+      console.log(`  ${filePath}${detail ? ` (${detail})` : ""}`);
     }
     if (missingTargets.length > 12) {
       console.log(`  ... ${missingTargets.length - 12} more`);
@@ -3789,6 +3913,26 @@ function uniqueEdgeFiles(value, field) {
     )
   ].sort();
 }
+function extractMissingTargetDetails(value) {
+  const details = /* @__PURE__ */ new Map();
+  if (!Array.isArray(value)) {
+    return details;
+  }
+  for (const item of value) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    const pathValue = typeof record.path === "string" ? record.path : void 0;
+    const reason = typeof record.reason === "string" ? record.reason : void 0;
+    const line = typeof record.line === "number" ? record.line : void 0;
+    if (!pathValue || !reason) {
+      continue;
+    }
+    details.set(pathValue, line ? `excluded: ${reason} at line ${line}` : `excluded: ${reason}`);
+  }
+  return details;
+}
 function printFileList(title, description, files) {
   const displayLimit = 12;
   console.log(`${title} (${files.length}) - ${description}`);
@@ -4075,14 +4219,17 @@ function buildLocalImpactResult(options) {
   const impactedFiles = [
     .../* @__PURE__ */ new Set([...incoming.map((edge) => edge.from), ...outgoing.map((edge) => edge.to)])
   ].sort();
-  const warnings = missingTargetFiles.length > 0 ? [
-    {
-      code: "local_impact_targets_missing",
-      severity: "warning",
-      message: "One or more requested impact targets are not present in the selected local overlay. Rebuild without --cached or rerun code sync with a larger --max-files value.",
-      files: missingTargetFiles
-    }
-  ] : [];
+  const relevantWarningFiles = /* @__PURE__ */ new Set([
+    ...selectedFiles,
+    ...impactedFiles,
+    ...incoming.map((edge) => edge.from),
+    ...outgoing.map((edge) => edge.to)
+  ]);
+  const missingTargetsWarning = buildMissingTargetsWarning(manifest, missingTargetFiles);
+  const warnings = [
+    ...missingTargetsWarning ? [missingTargetsWarning] : [],
+    ...impactOverlayWarnings(manifest.warnings, relevantWarningFiles)
+  ];
   return {
     title: "Local impact",
     caveat: "Local impact reports file-level import neighbors from the current checkout. Use --source hosted only when you want the hosted team graph.",
@@ -4090,6 +4237,7 @@ function buildLocalImpactResult(options) {
     target: symbol ? compactSymbol(symbol) : { changedFiles, missingTargetFiles },
     changedFiles,
     missingTargetFiles,
+    missingTargetDetails: missingTargetsWarning?.details ?? [],
     warnings,
     symbols: manifest.symbols.filter((item) => selectedFiles.has(item.filePath)).map(compactSymbol),
     incoming,

package/docs/launch/DEMO_SCRIPT.md

@@ -0,0 +1,132 @@
+# Demo Script
+
+Goal: produce a 15 to 30 second terminal recording that proves the first-run
+promise without depending on a private repo.
+
+## Recording Setup
+
+- Terminal size: 88 x 26 or similar.
+- Theme: high contrast, readable font, no prompt plugins that leak paths or
+  credentials.
+- Network is needed only for `npx` to fetch the package. The analysis command
+  uses `--source local`.
+- Do not record private repositories, environment variables, or secrets.
+
+## Deterministic Demo Repo
+
+Paste this into a clean shell:
+
+```bash
+DEMO_DIR="$(mktemp -d)"
+cd "$DEMO_DIR"
+git init >/dev/null
+git config user.email demo@example.com
+git config user.name Demo
+
+mkdir -p src/auth apps/web/src/lib/auth apps/web/src/app/api/auth/session
+
+cat > src/auth/cookies.ts <<'EOF'
+export function readCookie(name: string) {
+  return name;
+}
+EOF
+
+cat > src/auth/tokens.ts <<'EOF'
+export function verifyToken(token: string) {
+  return token.length > 0;
+}
+EOF
+
+cat > src/auth/session.ts <<'EOF'
+import { readCookie } from './cookies';
+import { verifyToken } from './tokens';
+
+export function readSession() {
+  return verifyToken(readCookie('session'));
+}
+EOF
+
+cat > apps/web/src/lib/auth/permissions.ts <<'EOF'
+import { readSession } from '../../../../src/auth/session';
+
+export function canReadAdmin() {
+  return readSession();
+}
+EOF
+
+cat > apps/web/src/app/api/auth/session/route.ts <<'EOF'
+import { readSession } from '../../../../../../src/auth/session';
+
+export function GET() {
+  return readSession();
+}
+EOF
+
+git add .
+git commit -m "demo repo" >/dev/null
+
+npx -y snipara-companion impact src/auth/session.ts --source local
+```
+
+Expected output shape:
+
+```text
+Code impact - local - src/auth/session.ts
+Source: local_overlay
+Reason: source_forced_local
+
+Incoming (2) - files that depend on this
+  apps/web/src/app/api/auth/session/route.ts
+  apps/web/src/lib/auth/permissions.ts
+
+Outgoing (2) - files this depends on
+  src/auth/cookies.ts
+  src/auth/tokens.ts
+
+Use --json for full overlay details.
+```
+
+## Asciinema
+
+```bash
+asciinema rec docs/launch/impact.cast
+# run the deterministic demo commands
+asciinema play docs/launch/impact.cast
+```
+
+Optional GIF conversion if `agg` is installed:
+
+```bash
+agg docs/launch/impact.cast docs/launch/impact.gif
+```
+
+## VHS
+
+Create `docs/launch/impact.tape`:
+
+```text
+Output docs/launch/impact.gif
+Set FontSize 18
+Set Width 1200
+Set Height 720
+Set TypingSpeed 50ms
+
+Type "npx -y snipara-companion impact src/auth/session.ts --source local"
+Enter
+Sleep 3s
+```
+
+Then run:
+
+```bash
+vhs docs/launch/impact.tape
+```
+
+## Review Checklist
+
+- The command appears in the first five seconds.
+- The words `Incoming` and `Outgoing` are visible without scrolling.
+- There is no login, browser, account setup, or `init`.
+- No private path, token, secret, or customer name appears.
+- If the output is empty or surprising, fix the CLI or use the issue template
+  before posting the demo.

package/docs/launch/LAUNCH_KIT.md

@@ -0,0 +1,84 @@
+# snipara-companion Launch Kit
+
+Use this when announcing `snipara-companion` or preparing a demo.
+
+## Positioning
+
+One-liner:
+
+> Ask your repo what breaks if you touch a file.
+
+Problem:
+
+AI coding agents often edit before they understand local blast radius, and long
+agent work loses continuity across compaction, handoffs, and cold starts.
+
+First-run command:
+
+```bash
+npx -y snipara-companion impact src/auth/session.ts --source local
+```
+
+Expected shape:
+
+```text
+Code impact - local - src/auth/session.ts
+Source: local_overlay
+Reason: source_forced_local
+
+Incoming (2) - files that depend on this
+  apps/web/src/lib/auth/permissions.ts
+  apps/web/src/app/api/auth/session/route.ts
+
+Outgoing (2) - files this depends on
+  src/auth/cookies.ts
+  src/auth/tokens.ts
+
+Use --json for full overlay details.
+```
+
+## What To Say
+
+- No global install, no init, no account for the local first run.
+- `impact` builds a local file-level code overlay from the current checkout.
+- Local mode is first-class for one repo, one machine, and one session.
+- Hosted Snipara is optional for team memory, semantic retrieval, cross-machine
+  presence, and outcome learning.
+- Agent continuity is the second hook: `.snipara/` keeps phase state, handoffs,
+  context packs, and verification breadcrumbs durable.
+
+## What Not To Say
+
+- Do not claim perfect AST call-site analysis. Local impact is file-level import
+  impact.
+- Do not imply hosted Snipara is required for the first run.
+- Do not say code is uploaded by default. `--source local` stays local.
+- Do not present local mode as degraded. It is complete for local repo impact
+  and workflow continuity.
+
+## Launch Checklist
+
+- Verify the published package:
+
+  ```bash
+  npm view snipara-companion version bin dist-tags --json
+  npx -y snipara-companion@latest --version
+  npx -y snipara-companion@latest impact src/index.ts --source local
+  ```
+
+- Record a 15 to 30 second terminal demo using
+  [DEMO_SCRIPT.md](./DEMO_SCRIPT.md).
+- Publish the GitHub README link and npm link together.
+- Post one problem-first version from [POSTS.md](./POSTS.md), not every channel
+  at once.
+- Watch GitHub issues for the first 48 hours and label:
+  `impact-feedback`, `docs-feedback`, `good-first-issue`, `privacy`, `bug`.
+- Turn repeated confusion into README edits before adding new features.
+
+## Primary Links
+
+- GitHub: <https://github.com/Snipara/snipara-companion>
+- npm: <https://www.npmjs.com/package/snipara-companion>
+- Full reference: [../FULL_REFERENCE.md](../FULL_REFERENCE.md)
+- Demo script: [DEMO_SCRIPT.md](./DEMO_SCRIPT.md)
+- Post drafts: [POSTS.md](./POSTS.md)

package/docs/launch/POSTS.md

@@ -0,0 +1,139 @@
+# Post Drafts
+
+Keep the message problem-first. Edit names, links, and examples before posting.
+
+## Short Social
+
+I built `snipara-companion` for the moment before an AI coding agent edits a
+file:
+
+```bash
+npx -y snipara-companion impact src/auth/session.ts --source local
+```
+
+No install, no init, no account. It asks your current checkout what depends on
+that file and what it imports. Local mode stays on your machine.
+
+GitHub: https://github.com/Snipara/snipara-companion
+
+## Hacker News
+
+Title:
+
+```text
+Show HN: Ask your repo what breaks if you touch a file
+```
+
+Body:
+
+```text
+I built snipara-companion, a small local CLI for AI coding sessions.
+
+The first command is:
+
+  npx -y snipara-companion impact src/auth/session.ts --source local
+
+It builds a local file-level code overlay from the current checkout and prints
+Incoming and Outgoing files, so an agent or developer can see the local blast
+radius before editing. No account, init, or hosted graph is required for that
+path.
+
+The second use case is agent continuity: phase state, handoffs, context packs,
+and verification breadcrumbs are written under .snipara/ so a later agent can
+resume without relying on chat history.
+
+It is not a perfect call-site analyzer. The local graph is import/file-level by
+design. Hosted Snipara is optional for team memory, semantic retrieval, and
+cross-project context.
+
+GitHub: https://github.com/Snipara/snipara-companion
+npm: https://www.npmjs.com/package/snipara-companion
+```
+
+## Reddit
+
+Suggested communities: `r/opensource`, `r/programming`, or a tool-specific
+community where self-promotion is allowed.
+
+```text
+I built a local CLI for the first minute of an AI coding session:
+
+  npx -y snipara-companion impact src/auth/session.ts --source local
+
+It prints the files that depend on the target and the files it imports, using a
+local file-level overlay from the current checkout. No account or hosted graph
+is required for that path.
+
+The other half is agent continuity: local .snipara/ workflow state, handoffs,
+context packs, and verification notes so work can survive compaction or handoff.
+
+I would especially like feedback on false positives/negatives in `impact`
+output across real repos.
+
+GitHub: https://github.com/Snipara/snipara-companion
+```
+
+## Product Hunt
+
+Tagline:
+
+```text
+Ask your repo what breaks before an AI agent edits it.
+```
+
+Description:
+
+```text
+snipara-companion is a local-first CLI for AI coding sessions. Run one npx
+command to see file-level impact from your current checkout, then keep longer
+agent work resumable with local workflow state, handoffs, and context packs.
+No account is needed for the local path.
+```
+
+## LinkedIn
+
+```text
+The riskiest part of many AI coding sessions is the first minute: the agent
+starts editing before it understands local blast radius.
+
+We made the first command in snipara-companion:
+
+  npx -y snipara-companion impact src/auth/session.ts --source local
+
+It builds a local file-level overlay from the current checkout and shows:
+
+- Incoming files that depend on the target
+- Outgoing files the target depends on
+- No account or hosted graph required for the local path
+
+The second piece is continuity: .snipara/ phase state, handoffs, context packs,
+and verification breadcrumbs so agent work can survive compaction and handoff.
+
+GitHub: https://github.com/Snipara/snipara-companion
+```
+
+## Maintainer Reply Snippets
+
+When someone asks whether it uploads code:
+
+```text
+The `--source local` path does not upload code. It builds a local overlay from
+the current checkout. Hosted Snipara is opt-in for team and cross-project
+features.
+```
+
+When someone expects call-site precision:
+
+```text
+The local overlay is intentionally file-level import impact, not a full
+call-site AST graph. That keeps the first run fast and account-free. Please
+open an issue if the file-level result is wrong or misleading for your repo.
+```
+
+When someone gets empty impact output:
+
+```text
+Please open an "Impact output is wrong or surprising" issue with the command,
+package version, language, and redacted output. The most useful repro is a tiny
+public repo or file pair that shows the missing edge.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "Snipara Git-style companion CLI for local workflow continuity, hooks, hosted context, and Mini Snipara OSS workflows",
   "main": "dist/index.js",
   "bin": {