productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/profile.js

@@ -0,0 +1,334 @@
+import { existsSync, mkdirSync, writeFileSync, appendFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { agentLogPath, nextAgentEventId, readAgentTelemetryConfig, resolveTesterId } from "./commands/agent.js";
+import { readJson } from "./jsonFile.js";
+import { fileStatKey, readMemoized, writeMemoized } from "./processMemo.js";
+// Roles that mean "lead with the product view": people who think in outcomes,
+// agreements, and proof before code. Engineers and designers keep the repo
+// read first (their raw surfaces are the point).
+export const PRODUCT_VIEW_ROLES = ["product", "founder", "executive"];
+// machine-wide-profile-v0: how you work is a fact about YOU, not about a repo —
+// the same reasoning that already puts the tester id under the home dir (one
+// human, one identity). So the profile's home is machine-wide by default:
+// answer once, and every project foo touches leads with your view. A per-repo
+// file is still honored as a deliberate override when someone wants a different
+// lens in one repo. FOO_STATE_DIR overrides the home for tests (mirrors the
+// tester-id resolution exactly).
+function machineStateDir() {
+    return process.env.FOO_STATE_DIR?.trim() || path.join(homedir(), ".foo");
+}
+export function machineProfilePath() {
+    return path.join(machineStateDir(), "profile.json");
+}
+// The per-repo override path. Not written by the survey (which is about the
+// person); present only when someone deliberately wants a repo-specific lens.
+export function profilePath(root) {
+    return path.join(root, ".foo", "profile.json");
+}
+function readProfileFile(file) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const parsed = readJson(file);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        // v1 files carried a single `role`; fold it into `roles` so nobody's
+        // first answer is lost to a schema change.
+        if (!parsed.roles && parsed.role)
+            parsed.roles = [parsed.role];
+        return parsed;
+    }
+    catch {
+        return null; // a corrupt profile never breaks a read (R-005)
+    }
+}
+// Precedence: a repo override wins over the machine-wide profile. This is the
+// same shape as telemetry (per-repo file can override the machine default).
+// Memoized per process (cli_performance-v0 R-002): profile reads happen on
+// several surfaces per invocation; the (mtime, size) key keeps an external
+// write — a test fixture, `foo profile redo` from another process — honest.
+const profileCache = new Map();
+export function loadProfile(root) {
+    const repoFile = profilePath(root);
+    const machineFile = machineProfilePath();
+    const key = `${fileStatKey(repoFile)}|${fileStatKey(machineFile)}`;
+    const cached = readMemoized(profileCache, root, key);
+    if (cached !== undefined)
+        return cached;
+    const value = readProfileFile(repoFile) ?? readProfileFile(machineFile);
+    writeMemoized(profileCache, root, key, value);
+    return value;
+}
+// Where the survey and `foo profile redo` write: machine-wide, so the answer
+// follows the person across every project. `scope: "repo"` writes the override.
+export function saveProfile(profile, opts) {
+    const file = opts?.scope === "repo" && opts.root ? profilePath(opts.root) : machineProfilePath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(profile, null, 2)}\n`);
+    // The machine file feeds every root's merge; a save is rare, so clearing the
+    // whole per-process memo is the simple honest invalidation.
+    profileCache.clear();
+}
+// The survey corpus (R-002): every user-visible survey string, exported as one
+// constant so the language eval scans exactly what renders — same contract as
+// FIRST_RUN_OPENER. productfoo voice: productfoo reads you the way it reads the project,
+// options teach what the answer changes, and nothing sounds like a form.
+export const SURVEY_INTRO = "It also reads you — a few quick questions so the work fits how you work. Enter skips any of them.";
+export const SURVEY_Q_ROLE = "What's your role? Pick any — this chooses the view productfoo leads with.  1 product · 2 engineer · 3 designer · 4 founder · 5 executive";
+export const SURVEY_Q_HARNESS = "Which coding agents do you build with? Pick any — productfoo offers to set up its commands in these.  1 Claude Code · 2 Cursor · 3 Codex · or type them";
+export const SURVEY_Q_BUILDING = "What are you building? A few words is plenty — this stays on your machine.";
+export const SURVEY_Q_TEAM = "Who's building with you?  1 just me · 2 a small team · 3 a bigger org";
+export const SURVEY_CLOSE_PRODUCT = "productfoo leads with the product view from here — no flags needed. Redo any time: foo profile";
+export const SURVEY_CLOSE_SAVED = "Saved — productfoo keeps this on your machine. Redo any time: foo profile";
+export const SURVEY_CLOSE_SKIPPED = "Nothing saved — productfoo stays as-is. Ask again any time: foo profile";
+export const SURVEY_DIDNT_CATCH = "didn't catch";
+export const PROFILE_NONE = "foo hasn't read you yet. Run it any time: foo profile redo";
+export const PROFILE_REDO_NEEDS_TTY = "Redo needs a live terminal — run foo profile redo where you can type.";
+export const SURVEY_CORPUS = [
+    SURVEY_INTRO,
+    SURVEY_Q_ROLE,
+    SURVEY_Q_HARNESS,
+    SURVEY_Q_BUILDING,
+    SURVEY_Q_TEAM,
+    SURVEY_CLOSE_PRODUCT,
+    SURVEY_CLOSE_SAVED,
+    SURVEY_CLOSE_SKIPPED,
+    SURVEY_DIDNT_CATCH,
+    PROFILE_NONE,
+    PROFILE_REDO_NEEDS_TTY,
+];
+const ROLE_BY_DIGIT = { "1": "product", "2": "engineer", "3": "designer", "4": "founder", "5": "executive" };
+const ROLE_LABELS = { product: "product", engineer: "engineer", designer: "designer", founder: "founder", executive: "executive" };
+const HARNESS_BY_DIGIT = { "1": "claude-code", "2": "cursor", "3": "codex" };
+const HARNESS_LABELS = { "claude-code": "Claude Code", cursor: "Cursor", codex: "Codex" };
+const TEAM_BY_DIGIT = { "1": "just-me", "2": "small-team", "3": "larger-org" };
+const TEAM_LABELS = { "just-me": "just you", "small-team": "a small team", "larger-org": "a bigger org" };
+// Lenient on purpose (T-004): "1, 3", "1 and 3", "product + agent", "pm" all
+// land. Digits and words both count; order kept; duplicates dropped.
+export function parseRoles(answer) {
+    const roles = [];
+    const push = (role) => {
+        if (role && !roles.includes(role))
+            roles.push(role);
+    };
+    for (const ch of answer)
+        push(ROLE_BY_DIGIT[ch]);
+    const lower = answer.toLowerCase();
+    if (/\b(product|pm)/.test(lower))
+        push("product");
+    if (/\b(eng|dev|code)/.test(lower))
+        push("engineer");
+    if (/\bdesign/.test(lower))
+        push("designer");
+    if (/\bfound/.test(lower))
+        push("founder");
+    if (/\b(exec|ceo|cpo|cto|vp)/.test(lower))
+        push("executive");
+    return roles;
+}
+export function parseTeam(answer) {
+    const direct = TEAM_BY_DIGIT[answer.trim()];
+    if (direct)
+        return direct;
+    const lower = answer.toLowerCase();
+    if (/\b(just me|solo|alone|me)\b/.test(lower))
+        return "just-me";
+    if (/\bsmall\b/.test(lower))
+        return "small-team";
+    if (/\b(big|large|org|company)/.test(lower))
+        return "larger-org";
+    return undefined;
+}
+// "Which do you build with MOST" — people lead with their main tool, so the
+// first recognized mention (digit or name) wins: "1, sometimes 3" is Claude
+// Code, "2 mostly, codex rarely" is Cursor. (Dogfood 2026-07-11: the digit was
+// only matched against the whole answer, and the owner's pick was missed.)
+const HARNESS_NAMES = { claude: "claude-code", cursor: "cursor", codex: "codex" };
+// #622: plural, like roles. "1, 3", "claude and codex", "cursor + claude" all
+// land, in the order given; duplicates dropped. With no known agent named, a
+// free-typed answer is kept as the single value (it is still the person's word).
+export function parseHarnesses(answer) {
+    const lower = answer.toLowerCase();
+    const hits = [];
+    for (const [name, id] of Object.entries(HARNESS_NAMES)) {
+        for (let at = lower.indexOf(name); at !== -1; at = lower.indexOf(name, at + 1))
+            hits.push({ at, id });
+    }
+    for (const [digit, id] of Object.entries(HARNESS_BY_DIGIT)) {
+        for (let at = answer.indexOf(digit); at !== -1; at = answer.indexOf(digit, at + 1))
+            hits.push({ at, id });
+    }
+    const ids = [];
+    for (const { id } of hits.sort((a, b) => a.at - b.at))
+        if (!ids.includes(id))
+            ids.push(id);
+    if (ids.length > 0)
+        return ids;
+    const typed = answer.trim();
+    return typed ? [typed] : [];
+}
+export function parseHarness(answer) {
+    return parseHarnesses(answer)[0];
+}
+/** Every harness a profile names, from the plural field or an older single one. */
+export function profileHarnesses(profile) {
+    if (profile?.harnesses?.length)
+        return [...profile.harnesses];
+    return profile?.harness ? [profile.harness] : [];
+}
+export function harnessLabel(id) {
+    return HARNESS_LABELS[id] ?? id;
+}
+// The read-back (T-004): foo answers the survey the way it answers a repo —
+// one Read: line naming exactly what it understood. This is the legibility
+// beat v1 was missing: a dropped answer becomes visible the moment it happens.
+export function renderProfileReadback(profile) {
+    const parts = [];
+    if (profile.roles?.length)
+        parts.push(profile.roles.map((role) => ROLE_LABELS[role]).join(" + "));
+    const harnesses = profileHarnesses(profile);
+    if (harnesses.length)
+        parts.push(harnesses.map(harnessLabel).join(" + "));
+    if (profile.building)
+        parts.push(`building ${profile.building}`);
+    if (profile.team)
+        parts.push(TEAM_LABELS[profile.team] ?? profile.team);
+    return parts.length ? `Read: ${parts.join(" · ")}.` : "";
+}
+export function surveyClose(profile) {
+    const answered = Boolean(profile.roles?.length || profile.harness || profile.building || profile.team);
+    if (profile.roles?.some((role) => PRODUCT_VIEW_ROLES.includes(role)))
+        return SURVEY_CLOSE_PRODUCT;
+    return answered ? SURVEY_CLOSE_SAVED : SURVEY_CLOSE_SKIPPED;
+}
+// Ask four optional questions. Answers remain on this machine.
+// Every answer is optional: Enter moves on, an answer productfoo can't place is named
+// out loud — `(didn't catch "…" — skipped)` — never silently dropped (T-004),
+// and the survey never nags (R-002/R-005). Streams are injected for tests.
+export async function runFirstRunSurvey(io, now = () => new Date().toISOString()) {
+    const rl = readline.createInterface({ input: io.input, output: io.output });
+    const ask = async (question) => (await rl.question(`${question}\n> `)).trim();
+    const missed = (answer) => io.output.write(`(${SURVEY_DIDNT_CATCH} "${answer}" — skipped)\n`);
+    try {
+        io.output.write(`${SURVEY_INTRO}\n\n`);
+        const roleAnswer = await ask(SURVEY_Q_ROLE);
+        const roles = parseRoles(roleAnswer);
+        if (roleAnswer && roles.length === 0)
+            missed(roleAnswer);
+        const harnesses = parseHarnesses(await ask(SURVEY_Q_HARNESS));
+        const building = (await ask(SURVEY_Q_BUILDING)) || undefined;
+        const teamAnswer = await ask(SURVEY_Q_TEAM);
+        const team = parseTeam(teamAnswer);
+        if (teamAnswer && !team)
+            missed(teamAnswer);
+        const profile = {
+            ...(roles.length ? { roles } : {}),
+            ...(harnesses.length ? { harnesses, harness: harnesses[0] } : {}),
+            ...(building ? { building } : {}),
+            ...(team ? { team } : {}),
+            answered_at: now(),
+        };
+        const readback = renderProfileReadback(profile);
+        if (readback)
+            io.output.write(`${readback}\n`);
+        io.output.write(`${surveyClose(profile)}\n\n`);
+        return profile;
+    }
+    finally {
+        rl.close();
+    }
+}
+// The report (R-004, amended by onboarding-trust-boundary-v0): picks only. A
+// free-typed harness reports as "other" so no free text ever rides along; the
+// `building` answer is structurally absent — the event is built from an
+// allowlist, not by filtering the profile.
+export function profileReportEvent(profile, version) {
+    if (!profile.roles?.length && !profile.harness && !profile.team)
+        return null;
+    return {
+        schema_version: "0.1",
+        event_type: "profile",
+        id: nextAgentEventId(),
+        timestamp: profile.answered_at,
+        version,
+        ...(profile.roles?.length ? { roles: profile.roles } : {}),
+        ...(profile.harness ? { harness: HARNESS_LABELS[profile.harness] ? profile.harness : "other" } : {}),
+        ...(profile.team ? { team: profile.team } : {}),
+    };
+}
+// Record bounded profile picks locally; free text stays only in the profile.
+export function reportProfile(root, profile, version, env = process.env) {
+    try {
+        const event = profileReportEvent(profile, version);
+        if (!event || env.DO_NOT_TRACK)
+            return undefined;
+        if (!readAgentTelemetryConfig(root).config.enabled)
+            return undefined;
+        const testerId = resolveTesterId(root);
+        const keyed = { ...event, ...(testerId ? { tester_id: testerId } : {}) };
+        const logPath = agentLogPath(root);
+        mkdirSync(path.dirname(logPath), { recursive: true });
+        appendFileSync(logPath, `${JSON.stringify(keyed)}\n`);
+        return undefined;
+    }
+    catch {
+        return undefined; // reporting never alters the read (R-005)
+    }
+}
+// `foo profile` (T-004): what productfoo knows about how you work, in the same Read:
+// grammar the survey closes with — plus where it lives and how to redo it.
+export function renderProfileStatus(root) {
+    const profile = loadProfile(root);
+    if (!profile)
+        return `${PROFILE_NONE}\n`;
+    const lines = [];
+    const readback = renderProfileReadback(profile);
+    lines.push(readback || "Nothing answered yet.");
+    const overriding = readProfileFile(profilePath(root)) !== null;
+    lines.push(overriding
+        ? "  This repo has its own profile (.foo/profile.json); what you typed free-form never leaves the machine."
+        : "  Lives on your machine and follows you across projects; what you typed free-form never leaves it.");
+    lines.push("  Redo any time: foo profile redo");
+    return `${lines.join("\n")}\n`;
+}
+// `foo profile redo` (T-004): the recovery path v1 didn't have. Re-runs the
+// same survey on a live terminal, saves, and records local profile picks.
+export async function runProfileRedo(root, version, io) {
+    const input = io?.input ?? process.stdin;
+    const output = io?.output ?? process.stdout;
+    const inputTTY = io?.inputTTY ?? Boolean(process.stdin.isTTY);
+    const outputTTY = io?.outputTTY ?? Boolean(process.stdout.isTTY);
+    if (!inputTTY || !outputTTY)
+        return `${PROFILE_REDO_NEEDS_TTY}\n`;
+    const profile = await runFirstRunSurvey({ input, output });
+    saveProfile(profile); // machine-wide: the answer follows the person
+    void reportProfile(root, profile, version);
+    return "";
+}
+export const PROFILE_SET_EMPTY = "Nothing to set — give at least one of --role, --harness, --team, --building.";
+export function runProfileSet(root, version, input, now = () => new Date().toISOString()) {
+    const roles = input.roles ? parseRoles(input.roles) : [];
+    const harnesses = input.harness ? parseHarnesses(input.harness) : [];
+    const team = input.team ? parseTeam(input.team) : undefined;
+    const building = input.building?.trim() || undefined;
+    if (!roles.length && !harnesses.length && !building && !team)
+        throw new Error(PROFILE_SET_EMPTY);
+    const profile = {
+        ...(roles.length ? { roles } : {}),
+        ...(harnesses.length ? { harnesses, harness: harnesses[0] } : {}),
+        ...(building ? { building } : {}),
+        ...(team ? { team } : {}),
+        answered_at: now(),
+    };
+    saveProfile(profile); // machine-wide: the profile is about the person
+    void reportProfile(root, profile, version);
+    if (input.json) {
+        // The free text is deliberately absent from the machine-readable echo the
+        // agent parses — the surface never invites it back out.
+        return `${JSON.stringify({ roles: profile.roles ?? [], harnesses: profileHarnesses(profile), harness: profile.harness ?? null, team: profile.team ?? null }, null, 2)}\n`;
+    }
+    const readback = renderProfileReadback(profile);
+    return `${readback ? `${readback}\n` : ""}${surveyClose(profile)}\n`;
+}

package/dist-public/src/questionModel.d.ts

@@ -0,0 +1,46 @@
+export type Confidence = "low" | "medium" | "high";
+export type QuestionOption = {
+    id: string;
+    label: string;
+    description?: string;
+};
+export type Judgment = {
+    belief: string;
+    evidence: string;
+    confidence: Confidence;
+    dissent?: string;
+};
+export type QuestionModel = {
+    header: string;
+    prompt: string;
+    options: QuestionOption[];
+    recommendedOptionId: string;
+    judgment: Judgment;
+    multiSelect: boolean;
+};
+export type QuestionInput = {
+    header: string;
+    prompt: string;
+    options: Array<{
+        id?: string;
+        label: string;
+        description?: string;
+    }>;
+    recommendedOptionId?: string;
+    judgment: Judgment;
+    multiSelect?: boolean;
+};
+export type ProjectedOption = QuestionOption & {
+    number: number;
+    recommended: boolean;
+};
+export type ProjectedQuestion = {
+    header: string;
+    prompt: string;
+    options: ProjectedOption[];
+    recommendedOptionId: string;
+    judgment: Judgment;
+    multiSelect: boolean;
+};
+export declare function defineQuestion(input: QuestionInput): QuestionModel;
+export declare function projectQuestion(model: QuestionModel): ProjectedQuestion;

package/dist-public/src/questionModel.js

@@ -0,0 +1,74 @@
+// Runtime-neutral question model for productfoo's branded question moment.
+//
+// Packet: specs/foo-branded-elicitation-v0 — T-002 (R-005 / R-006). One model, two
+// renderers: the numbered-text renderer (T-003) and the branded widget renderer (T-004)
+// both read this model and never hold their own option set or wording, so the surfaces
+// cannot drift. The model carries productfoo's question contract — a recommendation (R-005's
+// "recommend one"), numbered options, and the legible-judgment fields (belief, evidence,
+// confidence, dissent) — so a judgment surface is never reduced to a bare menu.
+const CONFIDENCE_VALUES = new Set(["low", "medium", "high"]);
+function defaultId(index) {
+    return `opt-${index + 1}`;
+}
+function validateJudgment(judgment) {
+    if (!judgment.belief.trim())
+        throw new Error("judgment.belief is required");
+    if (!judgment.evidence.trim())
+        throw new Error("judgment.evidence is required");
+    if (!CONFIDENCE_VALUES.has(judgment.confidence)) {
+        throw new Error("judgment.confidence must be one of low|medium|high");
+    }
+}
+// Build and validate a canonical QuestionModel. Throws on a malformed question so a
+// drifted or bare-menu question fails fast rather than rendering something wrong.
+export function defineQuestion(input) {
+    if (!input.header.trim())
+        throw new Error("question header is required");
+    if (!input.prompt.trim())
+        throw new Error("question prompt is required");
+    if (input.options.length < 2)
+        throw new Error("a question needs at least two options");
+    const options = input.options.map((option, index) => {
+        if (!option.label.trim())
+            throw new Error(`option ${index + 1} is missing a label`);
+        return { id: option.id?.trim() || defaultId(index), label: option.label, description: option.description };
+    });
+    const ids = options.map((option) => option.id);
+    if (new Set(ids).size !== ids.length)
+        throw new Error("option ids must be unique");
+    const recommendedOptionId = input.recommendedOptionId ?? options[0].id;
+    if (!ids.includes(recommendedOptionId)) {
+        throw new Error(`recommendedOptionId "${recommendedOptionId}" does not match any option`);
+    }
+    validateJudgment(input.judgment);
+    return {
+        header: input.header,
+        prompt: input.prompt,
+        options,
+        recommendedOptionId,
+        judgment: input.judgment,
+        multiSelect: input.multiSelect ?? false,
+    };
+}
+// Project the model into the render-agnostic shape both renderers consume: the
+// recommended option first, then the rest in author order, each numbered 1..n.
+export function projectQuestion(model) {
+    const recommended = model.options.find((option) => option.id === model.recommendedOptionId);
+    if (!recommended) {
+        throw new Error(`recommendedOptionId "${model.recommendedOptionId}" is not in options`);
+    }
+    const ordered = [recommended, ...model.options.filter((option) => option.id !== model.recommendedOptionId)];
+    const options = ordered.map((option, index) => ({
+        ...option,
+        number: index + 1,
+        recommended: option.id === model.recommendedOptionId,
+    }));
+    return {
+        header: model.header,
+        prompt: model.prompt,
+        options,
+        recommendedOptionId: model.recommendedOptionId,
+        judgment: model.judgment,
+        multiSelect: model.multiSelect,
+    };
+}

package/dist-public/src/questionText.d.ts

@@ -0,0 +1,7 @@
+import type { ElicitationSurface, SurfaceContext } from "./elicitationSurface.js";
+import type { QuestionModel } from "./questionModel.js";
+export declare function renderQuestionText(model: QuestionModel): string;
+export declare function renderQuestion(model: QuestionModel, context?: SurfaceContext): {
+    surface: ElicitationSurface;
+    text: string;
+};

package/dist-public/src/questionText.js

@@ -0,0 +1,38 @@
+// Numbered-text renderer for productfoo's branded question moment — the guaranteed fallback.
+//
+// Packet: specs/foo-branded-elicitation-v0 — T-003 (R-004 / R-005). Renders a
+// QuestionModel as productfoo's canonical numbered text: the recommended option first and
+// marked, every option numbered, the legible-judgment fields shown, and a reply-with-a-
+// number prompt. This is the surface every runtime can render and a coding agent can
+// read, so it is the fallback whenever the branded widget cannot render.
+import { detectElicitationSurface } from "./elicitationSurface.js";
+import { projectQuestion } from "./questionModel.js";
+// Render the model as canonical numbered text. Pure: the same model always renders the
+// same text, so the text path shows identical content whatever the widget could have
+// done (R-004 / C-006).
+export function renderQuestionText(model) {
+    const projected = projectQuestion(model);
+    const lines = [`${model.header} — ${model.prompt}`, ""];
+    for (const option of projected.options) {
+        lines.push(`  ${option.number}. ${option.label}${option.recommended ? "  (recommended)" : ""}`);
+        if (option.description)
+            lines.push(`     ${option.description}`);
+    }
+    lines.push("");
+    lines.push(`Why this pick: ${model.judgment.belief}`);
+    lines.push(`Evidence:      ${model.judgment.evidence}`);
+    lines.push(`Confidence:    ${model.judgment.confidence}`);
+    if (model.judgment.dissent)
+        lines.push(`Dissent:       ${model.judgment.dissent}`);
+    lines.push("");
+    const count = projected.options.length;
+    lines.push(model.multiSelect ? `Reply with one or more numbers (1-${count}).` : `Reply with a number (1-${count}).`);
+    return `${lines.join("\n")}\n`;
+}
+// Route a question to a surface and render it. The widget renderer lands in T-004; until
+// then the text renderer is the guaranteed fallback for every surface, which is exactly
+// the C-006 case (the widget is unavailable, so the text path renders identical content).
+export function renderQuestion(model, context) {
+    const decision = detectElicitationSurface(context);
+    return { surface: decision.surface, text: renderQuestionText(model) };
+}

package/dist-public/src/redactConfig.d.ts

@@ -0,0 +1,2 @@
+export declare const REDACT_ALLOW_FILE = ".foo-redact-allow";
+export declare function loadRepoAllowlist(root: string): string[];

package/dist-public/src/redactConfig.js

@@ -0,0 +1,11 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseAllowlist } from "./redactEngine.js";
+// Repo-level redaction allowlist (OQ2): a human-curated `.foo-redact-allow` at
+// the repo root, one literal value per line. Pairs with the inline
+// `foo-redact: allow` pragma. R-007: human-authored only, never auto-populated.
+export const REDACT_ALLOW_FILE = ".foo-redact-allow";
+export function loadRepoAllowlist(root) {
+    const file = path.join(root, REDACT_ALLOW_FILE);
+    return existsSync(file) ? parseAllowlist(readFileSync(file, "utf8")) : [];
+}

package/dist-public/src/redactEngine.d.ts

@@ -0,0 +1,59 @@
+export type Confidence = "high" | "medium" | "low";
+export type Finding = {
+    detector: string;
+    category: string;
+    confidence: Confidence;
+    line: number;
+    column: number;
+    length: number;
+    entropy?: number;
+};
+export type ScanResult = {
+    schema_version: "0.1";
+    findings: Finding[];
+    counts: {
+        high: number;
+        medium: number;
+        low: number;
+        total: number;
+    };
+};
+export type ScanOptions = {
+    allowlist?: string[];
+    allowlistPatterns?: RegExp[];
+    minEntropyLen?: number;
+    profiles?: string[];
+};
+export declare function shannonEntropy(value: string): number;
+export declare const PII_PROFILE = "pii";
+export declare const DEFAULT_PROFILES: string[];
+export declare function knownProfiles(): string[];
+export declare function scanText(text: string, options?: ScanOptions): ScanResult;
+export declare function parseAllowlist(text: string): string[];
+export type RedactThreshold = Confidence;
+export type RedactionReceipt = {
+    schema_version: "0.1";
+    redactions: number;
+    by_type: Record<string, number>;
+    by_confidence: {
+        high: number;
+        medium: number;
+        low: number;
+    };
+    placeholders: string[];
+    kept: Array<{
+        detector: string;
+        confidence: Confidence;
+        line: number;
+        column: number;
+        reason: string;
+    }>;
+};
+export type RedactionResult = {
+    redactedText: string;
+    receipt: RedactionReceipt;
+};
+export type RedactOptions = ScanOptions & {
+    threshold?: RedactThreshold;
+};
+export declare function redactText(text: string, options?: RedactOptions): RedactionResult;