productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/skillLocal.js

@@ -0,0 +1,463 @@
+// Canonical skills resolve from this installed package, with release or development trust.
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync, renameSync, rmSync, writeSync, } from "node:fs";
+import { userInfo } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { markFailure } from "./errorTaxonomy.js";
+import { BUNDLED_SKILL_TREE, BUNDLED_SKILL_TREE_DOMAIN } from "./skillClientPolicy.js";
+import { skillTreeSnapshot, topLevelSkillFolderCount } from "./skillTreeDigest.js";
+import { canonicalJson } from "./trustEnvelope.js";
+// Classify missing or unapproved local skills as expected command failures.
+export function markSkillFailure(kind, message) {
+    const mark = kind === "not-found"
+        ? { errorClass: "not_found", errorCode: "E_SKILL_NOT_FOUND", message }
+        : kind === "unapproved-source"
+            ? { errorClass: "gate_block", errorCode: "E_SKILL_SOURCE_UNAPPROVED", message }
+            : { errorClass: "io_error", errorCode: "E_IO", message };
+    markFailure(mark);
+}
+// productfoo's own package root (this file compiles to dist/src/skillLocal.js), so
+// a FULL install's bundled skills/ resolves from any working directory — root
+// (the caller's project) only covers dogfood/dev where cwd is the foo repo.
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+export class SkillDeliveryError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+    }
+}
+/**
+ * productfoo executes only skill text it can tie to an approval made on this machine:
+ * the bundled release digest, or a development tree the operator approved by
+ * exact digest. That refusal is the control that stops a caller repository
+ * shadowing a canonical skill with its own instructions.
+ *
+ * It is a refusal, not an outage. The old wording called it a trust boundary
+ * being "rebuilt" and told the reader to "use package-root skills" — which is
+ * what they were already doing, so the one command that clears it never
+ * appeared. Each condition now names itself and the command that fixes it.
+ */
+export function refuseUnapprovedSkillSource(reason) {
+    throw new SkillDeliveryError("unapproved-source", reason === "missing"
+        ? "This skill tree has not been approved on this machine. Review it, then approve that exact tree: `foo skill trust`."
+        : "This machine's skill approval no longer matches the skill tree — it was edited, it expired, or it was issued for another package root. Re-approve: `foo skill trust`.");
+}
+/** A missing bundled resource is a local installation error. */
+export function skillNotBundledMessage(name) {
+    return `"${name}" is not bundled with this productfoo install.`;
+}
+// A deliverable name is either a skill id ("pitch" → skills/pitch/SKILL.md) or
+// a markdown reference under a skill ("pitch/references/prfaq-template.md" →
+// that literal file). Every path segment must start alphanumeric, so ".." can
+// never form — this validator IS the traversal guard, used for every local read.
+export function skillRelPath(name) {
+    if (/^[a-z0-9][a-z0-9-]*$/.test(name))
+        return path.join(name, "SKILL.md");
+    if (/^[a-z0-9][a-z0-9-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)+$/.test(name) && name.endsWith(".md"))
+        return name;
+    return null;
+}
+const DEV_TRUST_SCHEMA = "1";
+const DEV_TRUST_KIND = "foo.development-skill-source";
+const DEV_TREE_HASH_DOMAIN = "foo.development-skill-tree.v1";
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+export function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+function canonicalTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value ? parsed : null;
+}
+function boundedApprovalDays(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 365) {
+        throw new TypeError("development trust validity must be a whole number of days from 1 through 365");
+    }
+    return value;
+}
+export function shellWord(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function approvalInterval(options) {
+    const issued_at = options.issued_at ?? new Date().toISOString();
+    const issuedAt = canonicalTimestamp(issued_at);
+    const days = boundedApprovalDays(options.days ?? 30);
+    if (issuedAt === null)
+        throw new TypeError("development trust approval requires a canonical issue time");
+    return {
+        issued_at,
+        expires_at: new Date(issuedAt + days * 86_400_000).toISOString(),
+    };
+}
+function canonicalSkillTreeSnapshot(rootValue, targetRelative) {
+    // The walk is shared with the bundled-install anchor (skillTreeDigest.ts) so
+    // a development record and the release anchor can never disagree about what
+    // "this exact tree" hashes to. The domain keeps the two digest namespaces
+    // distinct; existing development records verify exactly as before.
+    return skillTreeSnapshot(rootValue, DEV_TREE_HASH_DOMAIN, targetRelative);
+}
+export function createDevelopmentSkillTrustRecord(rootValue, validity) {
+    const root = realpathSync(rootValue);
+    const issuedAt = canonicalTimestamp(validity.issued_at);
+    const expiresAt = canonicalTimestamp(validity.expires_at);
+    if (issuedAt === null || expiresAt === null || expiresAt <= issuedAt) {
+        throw new TypeError("development trust record requires a valid canonical time interval");
+    }
+    return Object.freeze({
+        schema_version: DEV_TRUST_SCHEMA,
+        record_kind: DEV_TRUST_KIND,
+        root,
+        skills_sha256: canonicalSkillTreeSnapshot(root).hash,
+        issued_at: validity.issued_at,
+        expires_at: validity.expires_at,
+    });
+}
+export function developmentSkillTrustProposal(rootValue, options = {}) {
+    const record = createDevelopmentSkillTrustRecord(rootValue, approvalInterval(options));
+    return Object.freeze({
+        ...record,
+        record_path: path.resolve(options.record_path ?? defaultDevelopmentTrustRecord()),
+    });
+}
+function assertExternalTrustRecordPath(rootValue, recordPathValue) {
+    const root = realpathSync(rootValue);
+    const recordPath = path.resolve(recordPathValue);
+    if (recordPath === root || recordPath.startsWith(`${root}${path.sep}`)) {
+        throw new TypeError("development trust record must stay outside the productfoo checkout");
+    }
+    const parent = path.dirname(recordPath);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const parentReal = realpathSync(parent);
+    if ((lstatSync(parentReal).mode & 0o022) !== 0) {
+        throw new TypeError("development trust record directory must not be writable by other users");
+    }
+    const resolved = path.join(parentReal, path.basename(recordPath));
+    if (resolved === root || resolved.startsWith(`${root}${path.sep}`)) {
+        throw new TypeError("development trust record must stay outside the productfoo checkout");
+    }
+    if (existsSync(recordPath)) {
+        const existing = lstatSync(recordPath);
+        if (existing.isSymbolicLink() || !existing.isFile()) {
+            throw new TypeError("development trust record target must be a regular file, not a link");
+        }
+    }
+    return recordPath;
+}
+function writePrivateTrustRecord(recordPathValue, record) {
+    const recordPath = assertExternalTrustRecordPath(record.root, recordPathValue);
+    const parent = path.dirname(recordPath);
+    const temp = path.join(parent, `.${path.basename(recordPath)}.${process.pid}.${randomUUID()}.tmp`);
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        try {
+            const bytes = Buffer.from(`${canonicalJson(record)}\n`, "utf8");
+            writeSync(fd, bytes);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, recordPath);
+        chmodSync(recordPath, 0o600);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+    const parentFd = openSync(parent, "r");
+    try {
+        fsyncSync(parentFd);
+    }
+    finally {
+        closeSync(parentFd);
+    }
+}
+export function approveDevelopmentSkillTrust(rootValue, expectedSkillsSha256, options = {}) {
+    if (!SHA256_HEX.test(expectedSkillsSha256)) {
+        throw new TypeError("development trust approval requires the exact reviewed skill-tree SHA-256");
+    }
+    const proposal = developmentSkillTrustProposal(rootValue, options);
+    if (proposal.skills_sha256 !== expectedSkillsSha256) {
+        throw new TypeError("development skill tree changed after review; review the new digest before approval");
+    }
+    const { record_path, ...record } = proposal;
+    writePrivateTrustRecord(record_path, record);
+    return proposal;
+}
+export function readDevelopmentSkillTrust(rootValue, recordPath, targetRelative, nowValue = new Date().toISOString()) {
+    try {
+        let recordLink;
+        try {
+            recordLink = lstatSync(recordPath);
+        }
+        catch (error) {
+            return error?.code === "ENOENT"
+                ? { status: "missing" }
+                : { status: "refused" };
+        }
+        if (!recordLink.isFile() || recordLink.isSymbolicLink() || (recordLink.mode & 0o022) !== 0)
+            return { status: "refused" };
+        const recordReal = realpathSync(recordPath);
+        const packageReal = realpathSync(rootValue);
+        if (recordReal === packageReal || recordReal.startsWith(`${packageReal}${path.sep}`))
+            return { status: "refused" };
+        const parsed = JSON.parse(readFileSync(recordReal, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return { status: "refused" };
+        const record = parsed;
+        if (!exactKeys(record, ["schema_version", "record_kind", "root", "skills_sha256", "issued_at", "expires_at"]))
+            return { status: "refused" };
+        if (record.schema_version !== DEV_TRUST_SCHEMA || record.record_kind !== DEV_TRUST_KIND)
+            return { status: "refused" };
+        if (typeof record.root !== "string" || realpathSync(record.root) !== packageReal)
+            return { status: "refused" };
+        if (typeof record.skills_sha256 !== "string" || !SHA256_HEX.test(record.skills_sha256))
+            return { status: "refused" };
+        const issuedAt = canonicalTimestamp(record.issued_at);
+        const expiresAt = canonicalTimestamp(record.expires_at);
+        const now = canonicalTimestamp(nowValue);
+        if (issuedAt === null || expiresAt === null || now === null || issuedAt > now || now >= expiresAt)
+            return { status: "refused" };
+        const snapshot = canonicalSkillTreeSnapshot(packageReal, targetRelative);
+        if (record.skills_sha256 !== snapshot.hash)
+            return { status: "refused" };
+        return {
+            status: "ready",
+            root: packageReal,
+            skills_sha256: record.skills_sha256,
+            issued_at: record.issued_at,
+            expires_at: record.expires_at,
+            record_path: recordReal,
+            target_bytes: targetRelative === undefined ? undefined : snapshot.targetBytes,
+        };
+    }
+    catch {
+        return { status: "refused" };
+    }
+}
+export function inspectDevelopmentSkillTrust(rootValue, recordPath = defaultDevelopmentTrustRecord(), nowValue = new Date().toISOString()) {
+    const { target_bytes: _, ...status } = readDevelopmentSkillTrust(rootValue, recordPath, undefined, nowValue);
+    return status;
+}
+function defaultDevelopmentTrustRecord() {
+    return path.join(userInfo().homedir, ".foo", "trust", "development-skill-source.json");
+}
+/**
+ * The install-anchored half of canonical-skill trust (foo-open-source-transition-v0
+ * T-003). When this package's skills tree is exactly the tree the release
+ * anchored, the bytes are the reviewed ones — npm's tarball integrity binds the
+ * install and BUNDLED_SKILL_TREE binds every read — so a clean install runs a
+ * bundled skill with no hosted call, no token, and no per-machine approval.
+ * Returns null whenever the anchor cannot prove the tree (absent tree, walk
+ * error, digest or count drift); the caller then falls back to the development
+ * record, which refuses when absent. The fallback is fail-closed either way.
+ */
+function readBundledCanonicalSkill(rel, trust) {
+    try {
+        const anchor = trust.bundled_skill_tree ?? BUNDLED_SKILL_TREE;
+        const snapshot = skillTreeSnapshot(PACKAGE_ROOT, BUNDLED_SKILL_TREE_DOMAIN, rel);
+        if (snapshot.hash !== anchor.tree_sha256)
+            return null;
+        if (topLevelSkillFolderCount(PACKAGE_ROOT) !== anchor.skill_count)
+            return null;
+        const bytes = snapshot.targetBytes;
+        if (bytes === null)
+            return null;
+        const text = bytes.toString("utf8");
+        if (!Buffer.from(text, "utf8").equals(bytes))
+            return null;
+        return text;
+    }
+    catch {
+        // An incomplete install has no tree to walk and an unreadable tree cannot be
+        // proven; neither is an anchor case, and the dev-record fallback below
+        // still refuses honestly.
+        return null;
+    }
+}
+/**
+ * #897: doctor's view of the install-anchored path. True when this package's
+ * skills tree is exactly the release-anchored tree, so every bundled skill
+ * loads with no approval (readBundledCanonicalSkill). False when the tree is
+ * absent, unreadable, or edited; then `foo skill trust` is genuinely needed.
+ */
+export function bundledSkillTreeVerified(root = PACKAGE_ROOT, anchor = BUNDLED_SKILL_TREE) {
+    try {
+        return skillTreeSnapshot(root, BUNDLED_SKILL_TREE_DOMAIN).hash === anchor.tree_sha256
+            && topLevelSkillFolderCount(root) === anchor.skill_count;
+    }
+    catch {
+        return false;
+    }
+}
+function readTrustedCanonicalSkill(name, trust) {
+    const rel = skillRelPath(name);
+    if (rel === null)
+        throw new SkillDeliveryError("not-found", `skill "${name}" is not valid`);
+    const bundled = readBundledCanonicalSkill(rel, trust);
+    if (bundled !== null)
+        return bundled;
+    const recordPath = trust.development_trust_record ?? defaultDevelopmentTrustRecord();
+    // The read already tells missing (never approved) apart from refused (edited,
+    // expired, wrong root). Carry that distinction out to the reader instead of
+    // collapsing both into one "unavailable".
+    const read = readDevelopmentSkillTrust(PACKAGE_ROOT, recordPath, rel, trust.now);
+    if (read.status !== "ready")
+        return refuseUnapprovedSkillSource(read.status);
+    const bytes = read.target_bytes ?? null;
+    if (bytes === null)
+        return refuseUnapprovedSkillSource("refused");
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes))
+        return refuseUnapprovedSkillSource("refused");
+    return text;
+}
+// Resolve a skill from productfoo's own installed package and nowhere else.
+//
+// Skills ship on disk; a missing resource cannot fall back to a service.
+export function resolveLocalSkill(name, trust = {}) {
+    const rel = skillRelPath(name);
+    if (rel === null) {
+        throw new SkillDeliveryError("not-found", `"${name}" is not a valid skill name (a skill id like "pitch", or a reference like "pitch/references/prfaq-template.md").`);
+    }
+    if (!existsSync(path.join(PACKAGE_ROOT, "skills", rel)))
+        return null;
+    return { text: readTrustedCanonicalSkill(name, trust), source: "local" };
+}
+export { PACKAGE_ROOT, readTrustedCanonicalSkill, SHA256_HEX };
+// Resolve a skill only from productfoo's own installed package, never the caller repo.
+export async function resolveSkill(root, name, env = process.env, trust = {}) {
+    const rel = skillRelPath(name);
+    if (rel === null) {
+        throw new SkillDeliveryError("not-found", `"${name}" is not a valid skill name (a skill id like "pitch", or a reference like "pitch/references/prfaq-template.md").`);
+    }
+    const local = path.join(PACKAGE_ROOT, "skills", rel);
+    if (existsSync(local))
+        return { text: readTrustedCanonicalSkill(name, trust), source: "local" };
+    void root;
+    void env; // Legacy configuration cannot change the canonical skill source.
+    throw new SkillDeliveryError("not-found", skillNotBundledMessage(name));
+}
+async function runDevelopmentSkillTrustCommand(args) {
+    const json = args.includes("--json");
+    const knownFlags = new Set(["--json", "--approve", "--days", "--out"]);
+    const values = new Map();
+    for (let index = 1; index < args.length; index += 1) {
+        const flag = args[index];
+        if (!knownFlags.has(flag)) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: `unknown skill trust option ${flag}` });
+            return {
+                output: json
+                    ? `${JSON.stringify({ schema_version: "0.1", status: "refused", reason: "invalid_option" })}\n`
+                    : "usage: foo skill trust [--json] [--approve <sha256>] [--days 1..365] [--out <external-file>]\n",
+                exitCode: 1,
+            };
+        }
+        if (flag === "--json")
+            continue;
+        const value = args[index + 1];
+        if (!value || value.startsWith("--") || values.has(flag)) {
+            markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: `${flag} requires one value` });
+            return {
+                output: json
+                    ? `${JSON.stringify({ schema_version: "0.1", status: "refused", reason: "invalid_option" })}\n`
+                    : "usage: foo skill trust [--json] [--approve <sha256>] [--days 1..365] [--out <external-file>]\n",
+                exitCode: 1,
+            };
+        }
+        values.set(flag, value);
+        index += 1;
+    }
+    const daysText = values.get("--days");
+    const days = daysText === undefined
+        ? 30
+        : /^[1-9][0-9]{0,2}$/.test(daysText)
+            ? Number(daysText)
+            : Number.NaN;
+    const options = {
+        record_path: values.get("--out"),
+        days,
+    };
+    try {
+        const approvedDigest = values.get("--approve");
+        const proposal = approvedDigest
+            ? approveDevelopmentSkillTrust(PACKAGE_ROOT, approvedDigest, options)
+            : developmentSkillTrustProposal(PACKAGE_ROOT, options);
+        if (json) {
+            return {
+                output: `${JSON.stringify({
+                    schema_version: "0.1",
+                    status: approvedDigest ? "approved" : "review_required",
+                    root: proposal.root,
+                    skills_sha256: proposal.skills_sha256,
+                    issued_at: proposal.issued_at,
+                    expires_at: proposal.expires_at,
+                    record_path: proposal.record_path,
+                })}\n`,
+                exitCode: 0,
+            };
+        }
+        if (approvedDigest) {
+            return {
+                output: `Development skills approved for ${proposal.root}\nDigest: ${proposal.skills_sha256}\nExpires: ${proposal.expires_at}\nRecord: ${proposal.record_path}\n`,
+                exitCode: 0,
+            };
+        }
+        const approveCommand = [
+            "foo skill trust --approve",
+            proposal.skills_sha256,
+            "--days",
+            String(days),
+            "--out",
+            shellWord(proposal.record_path),
+        ].join(" ");
+        return {
+            output: `Review productfoo's canonical skill tree before approval.\nRoot: ${proposal.root}\nDigest: ${proposal.skills_sha256}\nProposed expiry: ${proposal.expires_at}\nExternal record: ${proposal.record_path}\nApprove only this exact digest with: ${approveCommand}\n`,
+            exitCode: 0,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "development trust approval refused";
+        markFailure({ errorClass: "gate_block", errorCode: "E_GATE_BLOCKED", message });
+        return {
+            output: json
+                ? `${JSON.stringify({ schema_version: "0.1", status: "refused", reason: message })}\n`
+                : `✋ needs your input — ${message}\n`,
+            exitCode: 1,
+        };
+    }
+}
+// CLI adapter: `foo skill <name>` prints the resolved leaf text — this is the
+// handoff surface harnesses use when no skills/ directory exists.
+export async function runSkillCommand(root, args, env = process.env, trust = {}) {
+    if (args[0] === "trust")
+        return runDevelopmentSkillTrustCommand(args);
+    const trustFlagIndex = args.indexOf("--dev-trust-record");
+    const trustRecord = trustFlagIndex === -1 ? trust.development_trust_record : args[trustFlagIndex + 1];
+    if (trustFlagIndex !== -1 && (!trustRecord || trustRecord.startsWith("--"))) {
+        markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: "development trust record path missing" });
+        return { output: "usage: foo skill <name> [--dev-trust-record <external-record.json>]\n", exitCode: 1 };
+    }
+    const name = args.find((arg, index) => !arg.startsWith("--")
+        && (trustFlagIndex === -1 || index !== trustFlagIndex + 1));
+    if (!name) {
+        markFailure({ errorClass: "usage_error", errorCode: "E_BAD_FLAG", message: "skill name missing" });
+        return { output: "usage: foo skill <name>\n", exitCode: 1 };
+    }
+    try {
+        const { text } = await resolveSkill(root, name, env, { ...trust, development_trust_record: trustRecord });
+        return { output: text.endsWith("\n") ? text : `${text}\n`, exitCode: 0 };
+    }
+    catch (err) {
+        if (err instanceof SkillDeliveryError) {
+            markSkillFailure(err.kind, err.message);
+            return { output: `${err.message}\n`, exitCode: 1 };
+        }
+        throw err;
+    }
+}

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

@@ -0,0 +1,9 @@
+export interface SkillTreeSnapshot {
+    /** Digest over the whole canonical tree under `domain`. */
+    hash: string;
+    /** Bytes of `targetRelative` (posix-style, relative to the skills root), when asked for. */
+    targetBytes: Buffer | null;
+}
+export declare function skillTreeSnapshot(rootValue: string, domain: string, targetRelative?: string): SkillTreeSnapshot;
+/** How many top-level folders the canonical tree carries (valid skill-id names only). */
+export declare function topLevelSkillFolderCount(rootValue: string): number;

package/dist-public/src/skillTreeDigest.js

@@ -0,0 +1,64 @@
+// One deterministic digest of a canonical skill tree, shared by every consumer
+// that has to agree on what "this exact tree" means: the development-trust
+// record (skillLocal.ts), the bundled-install anchor (skillClientPolicy.ts),
+// the anchor drift test, and scripts/skill-tree-anchor.mjs. A second
+// hand-written walk is exactly how two digests that claim to name the same
+// tree drift apart, so the walk lives here and nowhere else.
+//
+// The digest covers every regular file, symlink, and directory under each
+// top-level skill folder (folders whose names are valid skill ids), sorted
+// canonically, domain-separated by the caller's hash-domain string. Any
+// edit, addition, removal, or permission change under skills/ moves the hash.
+import { createHash } from "node:crypto";
+import { lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import path from "node:path";
+const compareNames = (left, right) => left.localeCompare(right);
+export function skillTreeSnapshot(rootValue, domain, targetRelative) {
+    const root = realpathSync(rootValue);
+    const skillsRoot = path.join(root, "skills");
+    const skillsReal = realpathSync(skillsRoot);
+    if (skillsReal !== skillsRoot)
+        throw new TypeError("development skills root must not be a symlink");
+    const normalizedTarget = targetRelative?.split(path.sep).join(path.posix.sep);
+    const entries = [];
+    const topLevel = readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && /^[a-z0-9][a-z0-9-]*$/.test(entry.name))
+        .sort((left, right) => compareNames(left.name, right.name));
+    const visit = (absolute, relative) => {
+        for (const entry of readdirSync(absolute, { withFileTypes: true }).sort((left, right) => compareNames(left.name, right.name))) {
+            const childAbsolute = path.join(absolute, entry.name);
+            const childRelative = path.posix.join(relative.split(path.sep).join(path.posix.sep), entry.name);
+            const stat = lstatSync(childAbsolute);
+            if (stat.isDirectory()) {
+                visit(childAbsolute, childRelative);
+            }
+            else if (stat.isFile()) {
+                entries.push({ relative: childRelative, kind: "file", bytes: readFileSync(childAbsolute) });
+            }
+            else if (stat.isSymbolicLink()) {
+                entries.push({ relative: childRelative, kind: "symlink", bytes: Buffer.from(readlinkSync(childAbsolute), "utf8") });
+            }
+            else {
+                throw new TypeError("development skill tree contains an unsupported filesystem object");
+            }
+        }
+    };
+    for (const entry of topLevel)
+        visit(path.join(skillsRoot, entry.name), entry.name);
+    const hash = createHash("sha256").update(`${domain}\0`, "utf8");
+    for (const entry of entries) {
+        hash.update(`${entry.kind}\0${entry.relative}\0${entry.bytes.length}\0`, "utf8");
+        hash.update(entry.bytes);
+    }
+    const target = normalizedTarget === undefined
+        ? null
+        : entries.find((entry) => entry.relative === normalizedTarget && entry.kind === "file")?.bytes ?? null;
+    return { hash: hash.digest("hex"), targetBytes: target === null ? null : Buffer.from(target) };
+}
+/** How many top-level folders the canonical tree carries (valid skill-id names only). */
+export function topLevelSkillFolderCount(rootValue) {
+    const skillsRoot = path.join(realpathSync(rootValue), "skills");
+    return readdirSync(realpathSync(skillsRoot), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && /^[a-z0-9][a-z0-9-]*$/.test(entry.name))
+        .length;
+}

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

@@ -0,0 +1,62 @@
+export type FetchLike = typeof globalThis.fetch;
+export type SlackRuntimeErrorCode = "not_connected" | "auth_expired" | "access_denied" | "provider_failure" | "network" | "provider_timeout" | "thread_too_large" | "budget_exhausted";
+export declare class SlackRuntimeError extends Error {
+    readonly code: SlackRuntimeErrorCode;
+    constructor(code: SlackRuntimeErrorCode, message: string);
+}
+export type SlackConnection = {
+    connection_ref: string;
+    broker: "nango" | "direct";
+    token: string;
+};
+export type SlackResponseEnvelope = Record<string, unknown>;
+export declare const SLACK_POLICY: {
+    readonly policy_version: "slack-local-worker-0.1";
+    readonly max_response_bytes: number;
+    readonly fetch_timeout_ms: 90000;
+    readonly max_model_input_tokens: 100000;
+    readonly max_replies_per_thread: 200;
+    readonly min_request_interval_ms: 1100;
+    readonly max_channels_probed: 10;
+};
+export type SlackConnectionEnv = Record<string, string | undefined>;
+export declare function slackConnectionConfigured(env: SlackConnectionEnv): boolean;
+export declare function slackCredentialBroker(env: SlackConnectionEnv): "nango" | "direct" | null;
+export declare function resolveSlackConnection(input: {
+    env: SlackConnectionEnv;
+    fetchImpl: FetchLike;
+}): Promise<SlackConnection>;
+export type SlackMessage = {
+    ts?: string;
+    user?: string;
+    bot_id?: string;
+    subtype?: string;
+    text?: string;
+};
+export type SlackThreadRead = {
+    messages: SlackMessage[];
+    has_more: boolean;
+};
+export declare class SlackClient {
+    readonly requests: {
+        conversations_list: number;
+        conversations_info: number;
+        conversations_history: number;
+        conversations_replies: number;
+    };
+    private readonly connection;
+    private readonly options;
+    private lastRequestAt;
+    constructor(connection: SlackConnection, options?: Partial<{
+        fetchImpl: FetchLike;
+        baseUrl: string;
+        now: () => number;
+        sleep: (ms: number) => Promise<void>;
+        fetchTimeoutMs: number;
+    }>);
+    private request;
+    probeWorkspace(): Promise<{
+        channels: number;
+    }>;
+    threadReplies(channelId: string, threadTs: string): Promise<SlackThreadRead>;
+}