@aacombarro89/praxis 0.1.0

package/dist/external.js

@@ -0,0 +1,155 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { resolvePackages } from "./packages.js";
+/**
+ * External installer packages (docs/wiki/external-packages.md, the bounded
+ * execution relaxation — see docs/wiki/decisions.md). A "rules"/"permissions"/
+ * "commands" package ships tool-neutral source that the *pure* emit pipeline
+ * (src/emit.ts) translates and writes. An "external" package ships no source
+ * at all — only a pinned install command that some other tool (npx/git) runs
+ * to drop its own already-tool-shaped files into the methodology layer (e.g.
+ * `.claude/skills/…`).
+ *
+ * That's side-effecting and untranslatable, so it never becomes an `EmitOp`.
+ * This module is the separate, explicit seam: `planExternal` decides *what*
+ * would happen (pure, no I/O — same plan/apply split as src/emit.ts +
+ * src/sync.ts), and `executeAction` is the one place that actually shells out,
+ * with the runner injected so tests never really execute a command.
+ */
+const LOCK_FILE = "praxis-external.lock";
+// One row per (package, target) pair Praxis has installed. No timestamps —
+// the pinned spec is the whole identity, so the lock is stable in git and
+// re-syncing is deterministic: same spec ⇒ same action.
+const lockEntrySchema = z.strictObject({
+    name: z.string().min(1),
+    spec: z.array(z.string().min(1)).min(1),
+    targets: z.array(z.string().min(1)).min(1),
+});
+const lockSchema = z.strictObject({
+    version: z.literal(1),
+    installed: z.array(lockEntrySchema).default([]),
+});
+export const EMPTY_LOCK = { version: 1, installed: [] };
+/**
+ * Decide what `sync` would do with every selected external package, against
+ * the current lock. Pure: the lock is injected so this is testable without
+ * disk, and it performs no execution itself.
+ *
+ * - `install`: no lock entry for this package yet.
+ * - `reinstall`: lock entry exists but its spec/targets no longer match the
+ *   package's current declaration (the manifest changed under it).
+ * - `skip`: lock entry matches exactly — idempotent no-op.
+ * - `orphan`: a lock entry exists for a package no longer selected (or with
+ *   no targets left after quarantine) — offer to remove, never silently.
+ */
+export function planExternal(manifest, lock) {
+    const packages = resolvePackages(manifest.packages).filter((p) => p.provides.includes("external"));
+    const manifestTargets = new Set(manifest.targets);
+    const actions = [];
+    const seen = new Set();
+    for (const pkg of packages) {
+        const block = pkg.external;
+        if (!block)
+            continue; // schema guarantees this is unreachable; guard for type-narrowing only
+        const targets = block.targets.filter((t) => manifestTargets.has(t));
+        seen.add(pkg.name);
+        const existing = lock.installed.find((e) => e.name === pkg.name);
+        if (targets.length === 0) {
+            // Fully quarantined out for this manifest's targets: nothing to run. If a
+            // prior sync installed it for targets no longer selected, that's an orphan.
+            if (existing) {
+                actions.push({ kind: "orphan", name: pkg.name, targets: existing.targets, command: block.uninstall });
+            }
+            continue;
+        }
+        if (!existing) {
+            actions.push({ kind: "install", name: pkg.name, targets, command: block.command });
+            continue;
+        }
+        const specMatches = arraysEqual(existing.spec, block.command) && arraysEqual([...existing.targets].sort(), [...targets].sort());
+        actions.push(specMatches
+            ? { kind: "skip", name: pkg.name, targets }
+            : { kind: "reinstall", name: pkg.name, targets, command: block.command });
+    }
+    // Lock entries for packages no longer selected at all are orphans too.
+    for (const entry of lock.installed) {
+        if (seen.has(entry.name))
+            continue;
+        const uninstall = lookupUninstall(entry.name);
+        actions.push({ kind: "orphan", name: entry.name, targets: entry.targets, command: uninstall });
+    }
+    return actions;
+}
+/** Look up a previously-installed package's declared uninstall argv, if the
+ *  package is still discoverable (it may have been removed entirely from
+ *  `packages/external/`, in which case removal stays warn-only). */
+function lookupUninstall(name) {
+    try {
+        return resolvePackages([name])[0]?.external?.uninstall;
+    }
+    catch {
+        return undefined;
+    }
+}
+function arraysEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+/** Runs one argv in `cwd`. The real implementation for `executeAction`'s
+ *  injected runner — uses `execFileSync` (argv form, no shell string) so
+ *  there is no pipe/shell-injection surface from a pinned command. */
+export function runCommand(command, cwd) {
+    if (command.length === 0)
+        throw new Error("runCommand: empty argv");
+    const [bin, ...args] = command;
+    execFileSync(bin, args, { cwd, stdio: "inherit" });
+}
+/** Execute one planned action via the injected runner. Tests pass a stub
+ *  runner so they never actually shell out. No-op for `skip`, and for
+ *  `orphan` when the package declared no `uninstall` (Praxis doesn't own
+ *  those files and never deletes them on the user's behalf). */
+export function executeAction(action, cwd, runner = runCommand) {
+    if (action.kind === "skip")
+        return;
+    if (action.kind === "orphan" && !action.command)
+        return; // warn-only; caller reports it
+    if (!action.command)
+        return;
+    runner(action.command, cwd);
+}
+/** Read `praxis-external.lock` from `cwd`, or the empty lock if absent. */
+export function readLock(cwd) {
+    const path = join(cwd, LOCK_FILE);
+    if (!existsSync(path))
+        return EMPTY_LOCK;
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return lockSchema.parse(raw);
+}
+/** Apply a list of executed actions to a lock, returning the next lock.
+ *  Pure — the caller decides whether/when to persist it. */
+export function applyActionsToLock(lock, actions) {
+    let installed = lock.installed;
+    for (const action of actions) {
+        if (action.kind === "install" || action.kind === "reinstall") {
+            installed = [
+                ...installed.filter((e) => e.name !== action.name),
+                { name: action.name, spec: action.command ?? [], targets: action.targets },
+            ];
+        }
+        else if (action.kind === "orphan") {
+            installed = installed.filter((e) => e.name !== action.name);
+        }
+    }
+    return { version: 1, installed };
+}
+/** Persist the lock to `praxis-external.lock` at `cwd`, sorted for a stable
+ *  diff (deterministic, reviewable — no timestamps anywhere in the file). */
+export function writeLock(cwd, lock) {
+    const sorted = {
+        version: 1,
+        installed: [...lock.installed].sort((a, b) => a.name.localeCompare(b.name)),
+    };
+    writeFileSync(join(cwd, LOCK_FILE), `${JSON.stringify(sorted, null, 2)}\n`, "utf8");
+}
+//# sourceMappingURL=external.js.map

package/dist/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../src/external.ts"],"names":[],"mappings":"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"}

package/dist/init.d.ts

@@ -0,0 +1,45 @@
+import { type Manifest, type Stack, type Target } from "./manifest.js";
+import { type SyncReport } from "./sync.js";
+/**
+ * `init` — the first-run install (docs/wiki/interaction-model.md, D17). Minimal by design:
+ * detect context → propose a default manifest → preview the emit → write
+ * `praxis.yaml` and apply. The richer "Customize" wizard is deferred until Layer 2
+ * gives real choices (one package, two targets today — nothing to pick yet).
+ *
+ * This module is pure logic; the interactive prompts live in src/program.ts.
+ */
+export interface InitContext {
+    hasGit: boolean;
+    hasClaudeMd: boolean;
+    hasAgentsMd: boolean;
+    /** A `praxis.yaml` already exists — init should defer to `sync`. */
+    manifestExists: boolean;
+    /** Stacks detected from project files. Empty for a bare/unrecognised repo. */
+    detectedStacks: Stack[];
+}
+export declare function detectContext(cwd: string): InitContext;
+/**
+ * The default manifest for a fresh repo: all Layer 1 packages + Layer 2 packages
+ * for the detected stacks. Data-driven from availablePackages(); no hardcoded list.
+ * Emits to both supported targets.
+ */
+export declare function defaultManifest(ctx: InitContext): Manifest;
+/**
+ * Build a manifest from explicit selections (Customize branch). Pure — no I/O, no prompts.
+ * Omits `stacks` when the array is empty.
+ */
+export declare function manifestFromSelections(stacks: Stack[], packages: string[], targets: Target[]): Manifest;
+/** Render a manifest as a commented `praxis.yaml`. Hand-written (not yaml.stringify)
+ *  so the file carries guidance for the human who owns it. */
+export declare function renderManifestYaml(manifest: Manifest): string;
+export interface InitPreview {
+    ctx: InitContext;
+    manifest: Manifest;
+    manifestYaml: string;
+    /** Dry-run emit report: what files init would create/update. */
+    report: SyncReport;
+}
+/** Compute everything init would do, writing nothing. */
+export declare function previewInit(cwd: string): InitPreview;
+/** Write `praxis.yaml` and apply the methodology files. */
+export declare function applyInit(cwd: string, manifest: Manifest): SyncReport;

package/dist/init.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { METHODOLOGY_VERSION, STACKS } from "./manifest.js";
+import { availablePackages } from "./packages.js";
+import { applyManifest } from "./sync.js";
+const MANIFEST_FILE = "praxis.yaml";
+export function detectContext(cwd) {
+    const has = (rel) => existsSync(join(cwd, rel));
+    const stacks = [];
+    // python-backend: pyproject.toml, requirements.txt, or setup.py
+    if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) {
+        stacks.push("python-backend");
+    }
+    // node: package.json present
+    if (has("package.json")) {
+        stacks.push("node");
+        // react: package.json has "react" in dependencies or devDependencies
+        try {
+            const raw = readFileSync(join(cwd, "package.json"), "utf8");
+            const pkg = JSON.parse(raw);
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if ("react" in deps) {
+                stacks.push("react");
+            }
+        }
+        catch {
+            // malformed or missing — no node/react crash; node is already pushed above
+        }
+    }
+    // Return in canonical STACKS order for determinism
+    const ordered = STACKS.filter((s) => stacks.includes(s));
+    return {
+        hasGit: has(".git"),
+        hasClaudeMd: has("CLAUDE.md"),
+        hasAgentsMd: has("AGENTS.md"),
+        manifestExists: has(MANIFEST_FILE),
+        detectedStacks: ordered,
+    };
+}
+/**
+ * The default manifest for a fresh repo: all Layer 1 packages + Layer 2 packages
+ * for the detected stacks. Data-driven from availablePackages(); no hardcoded list.
+ * Emits to both supported targets.
+ */
+export function defaultManifest(ctx) {
+    const all = availablePackages();
+    const detectedSet = new Set(ctx.detectedStacks);
+    const layer1 = [];
+    const layer2 = [];
+    for (const [name, pkg] of all) {
+        if (pkg.layer === "layer1") {
+            layer1.push(name);
+        }
+        else if (pkg.layer === "layer2" && pkg.stack && detectedSet.has(pkg.stack)) {
+            layer2.push(name);
+        }
+        // external and decision: excluded from quick-start
+    }
+    layer1.sort();
+    layer2.sort();
+    const manifest = {
+        version: 1,
+        methodology: METHODOLOGY_VERSION,
+        targets: ["claude-code", "agents-md"],
+        packages: [...layer1, ...layer2],
+    };
+    if (ctx.detectedStacks.length > 0) {
+        manifest.stacks = ctx.detectedStacks;
+    }
+    return manifest;
+}
+/**
+ * Build a manifest from explicit selections (Customize branch). Pure — no I/O, no prompts.
+ * Omits `stacks` when the array is empty.
+ */
+export function manifestFromSelections(stacks, packages, targets) {
+    const manifest = {
+        version: 1,
+        methodology: METHODOLOGY_VERSION,
+        targets,
+        packages,
+    };
+    if (stacks.length > 0) {
+        manifest.stacks = stacks;
+    }
+    return manifest;
+}
+/** Render a manifest as a commented `praxis.yaml`. Hand-written (not yaml.stringify)
+ *  so the file carries guidance for the human who owns it. */
+export function renderManifestYaml(manifest) {
+    const lines = [
+        "# praxis.yaml — the methodology installed in this repo (the declarative truth).",
+        "# Edit this, then run `praxis sync`. `praxis check` reports drift.",
+        `version: ${manifest.version}`,
+        `methodology: "${manifest.methodology}"`,
+    ];
+    if (manifest.stacks?.length)
+        lines.push(`stacks: [${manifest.stacks.join(", ")}]`);
+    lines.push(`targets: [${manifest.targets.join(", ")}]`);
+    lines.push(`packages: [${manifest.packages.join(", ")}]`);
+    return `${lines.join("\n")}\n`;
+}
+/** Compute everything init would do, writing nothing. */
+export function previewInit(cwd) {
+    const ctx = detectContext(cwd);
+    const manifest = defaultManifest(ctx);
+    return {
+        ctx,
+        manifest,
+        manifestYaml: renderManifestYaml(manifest),
+        report: applyManifest(manifest, cwd, false),
+    };
+}
+/** Write `praxis.yaml` and apply the methodology files. */
+export function applyInit(cwd, manifest) {
+    const path = join(cwd, MANIFEST_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, renderManifestYaml(manifest), "utf8");
+    return applyManifest(manifest, cwd, true);
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * The manifest — `praxis.yaml` (docs/wiki/interaction-model.md, decision D4). The visible,
+ * committed, hand-editable declarative truth: what methodology a repo has
+ * installed. `sync` reconciles the repo to it; this module reads and validates it.
+ *
+ * Enums are restricted to what Praxis can actually honor today. Accepting config
+ * we can't act on (an unimplemented target/stack) would be a silent lie — better
+ * a clear validation error. The lists grow as emitters and stacks land.
+ */
+export declare const METHODOLOGY_VERSION = "0.1.0";
+declare const TARGETS: readonly ["claude-code", "agents-md"];
+export declare const STACKS: readonly ["python-backend", "node", "react"];
+export declare const manifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    methodology: z.ZodString;
+    stacks: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "python-backend": "python-backend";
+        node: "node";
+        react: "react";
+    }>>>;
+    targets: z.ZodArray<z.ZodEnum<{
+        "claude-code": "claude-code";
+        "agents-md": "agents-md";
+    }>>;
+    packages: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type Manifest = z.infer<typeof manifestSchema>;
+export type Target = (typeof TARGETS)[number];
+export type Stack = (typeof STACKS)[number];
+/** Parse + validate manifest text. Throws an Error with a readable, multi-line
+ *  message naming each problem and where it is — written to be acted on. */
+export declare function parseManifest(yamlText: string): Manifest;
+/** Read and validate the manifest at `path`. */
+export declare function loadManifest(path: string): Manifest;
+export {};

package/dist/manifest.js

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+/**
+ * The manifest — `praxis.yaml` (docs/wiki/interaction-model.md, decision D4). The visible,
+ * committed, hand-editable declarative truth: what methodology a repo has
+ * installed. `sync` reconciles the repo to it; this module reads and validates it.
+ *
+ * Enums are restricted to what Praxis can actually honor today. Accepting config
+ * we can't act on (an unimplemented target/stack) would be a silent lie — better
+ * a clear validation error. The lists grow as emitters and stacks land.
+ */
+// The version of methodology content Praxis currently ships. `init` stamps new
+// manifests with it; `sync` offers to bump a repo to it (D6).
+export const METHODOLOGY_VERSION = "0.1.0";
+// Emit targets with an implemented emitter. Grows as emitters are added.
+const TARGETS = ["claude-code", "agents-md"];
+// Stacks Praxis knows. Grows as Layer 2 stacks are added.
+export const STACKS = ["python-backend", "node", "react"];
+export const manifestSchema = z.strictObject({
+    version: z.literal(1),
+    methodology: z.string().min(1),
+    // Optional: Layer 1 is stack-agnostic, so a repo installing only general
+    // methodology (like Praxis itself) declares no stacks. Present only when Layer 2
+    // recipes are wanted — and a repo can be more than one stack at once (e.g. a
+    // React frontend with a Node backend), so it is a list.
+    stacks: z.array(z.enum(STACKS)).optional(),
+    targets: z.array(z.enum(TARGETS)).min(1),
+    // Package names are free strings until a package registry exists to validate
+    // them against; the loader (a later phase) resolves requires/conflicts.
+    packages: z.array(z.string().min(1)).min(1),
+});
+/** Parse + validate manifest text. Throws an Error with a readable, multi-line
+ *  message naming each problem and where it is — written to be acted on. */
+export function parseManifest(yamlText) {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (err) {
+        throw new Error(`praxis.yaml is not valid YAML: ${err.message}`);
+    }
+    const result = manifestSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.map(String).join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new Error(`praxis.yaml is invalid:\n${issues}`);
+    }
+    return result.data;
+}
+/** Read and validate the manifest at `path`. */
+export function loadManifest(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new Error(`No praxis.yaml found at ${path}. Run \`praxis\` to create one.`);
+    }
+    return parseManifest(text);
+}
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,+EAA+E;AAC/E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,yEAAyE;AACzE,MAAM,OAAO,GAAG,CAAC,aAAa,EAAE,WAAW,CAAU,CAAC;AAEtD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,yEAAyE;IACzE,iFAAiF;IACjF,6EAA6E;IAC7E,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,6EAA6E;IAC7E,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC5C,CAAC,CAAC;AAMH;4EAC4E;AAC5E,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kCAAmC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC3E,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,iCAAiC,CACjE,CAAC;IACJ,CAAC;IACD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/merge-json.d.ts

@@ -0,0 +1,83 @@
+/**
+ * JSON-aware managed merge for `.claude/settings.json` (docs/wiki/merge-engine.md,
+ * decisions D10/D11/D18/D19). The markdown engine in `src/merge.ts` owns spans of *text*
+ * delimited by HTML-comment markers; that trick has **no JSON equivalent** — JSON
+ * has no comments. So this module is the structured-config analogue: Praxis owns
+ * only the **individual entries** it emits — permission rule strings, marketplace
+ * declarations, enabled-plugin keys — deep-merged into the host file, and records
+ * exactly which entries are its own in a self-contained top-level `_praxis` key
+ * (the JSON-native marker; D11 — no separate lockfile). One reconcile pass owns
+ * the whole file so two concerns (permissions, plugins) never compose into two
+ * separate writes of the same path (the same-file compose bug).
+ *
+ * Invariants (mirrors the markdown engine, verified by conformance):
+ *   - User-added entries in the same structures survive untouched (per-entry
+ *     ownership).
+ *   - Entries Praxis previously emitted but no longer ships are removed on update.
+ *   - If the user edited/removed one of Praxis's managed entries, that group is a
+ *     **conflict, never a clobber** (D10): left exactly as-is, surfaced.
+ *   - Idempotent: re-merging identical input is a byte-for-byte no-op.
+ *   - Every other key in the file (model, env, defaultMode, …) is preserved.
+ *
+ * The `_praxis` key is a valid top-level addition: the Claude Code settings schema
+ * sets top-level `additionalProperties: true` (verified against
+ * json.schemastore.org/claude-code-settings.json), while `permissions` itself is
+ * `additionalProperties: false` — hence the marker lives as a top-level sibling of
+ * `permissions`/`extraKnownMarketplaces`/`enabledPlugins`, never inside them.
+ */
+/** The three permission buckets Praxis manages, in stable emit order. */
+export declare const BUCKETS: readonly ["allow", "ask", "deny"];
+export type Bucket = (typeof BUCKETS)[number];
+/** A set of concrete, already-tool-translated rule strings per bucket. */
+export type RuleSet = Record<Bucket, string[]>;
+/** A Claude Code plugin marketplace source (today: github repo, optionally
+ *  pinned by ref/sha — see src/plugins.ts for the validated package shape). */
+export interface MarketplaceSource {
+    source: "github";
+    repo: string;
+    ref?: string;
+    sha?: string;
+}
+/** One marketplace declaration, keyed by its name. */
+export interface MarketplaceEntry {
+    name: string;
+    source: MarketplaceSource;
+}
+/** The desired plugin-marketplace state: marketplaces to declare and
+ *  "<plugin>@<marketplace>" keys to enable. */
+export interface PluginsDesired {
+    marketplaces: MarketplaceEntry[];
+    enable: string[];
+}
+export interface JsonReconcileResult {
+    /** The resulting file text (pretty-printed JSON, trailing newline). */
+    text: string;
+    /** Whether any byte changed. */
+    changed: boolean;
+    /** Group ids (`permissions.allow`, `plugins.marketplaces`, `plugins.enable`)
+     *  the user edited; left untouched. */
+    conflicts: string[];
+}
+/** Settings this reconcile pass should bring the host file in line with. Either
+ *  may be omitted — a sync that emits only permissions (or only plugins) leaves
+ *  the other concern's previously-managed entries alone, neither adding nor
+ *  removing them, since "omitted" here means "this op didn't run," not "empty." */
+export interface DesiredSettings {
+    permissions?: RuleSet;
+    plugins?: PluginsDesired;
+}
+/**
+ * Bring `.claude/settings.json` in line with the desired permissions and/or
+ * plugin-marketplace state in a single pass — the only function that may write
+ * this file, so permissions and plugins compose into one write instead of two
+ * operations racing on the same path. Splices only the entries Praxis owns;
+ * preserves user entries and every unrelated key; refuses to overwrite a group
+ * the user has edited (conflict). Pure; no I/O.
+ *
+ * @param existing  the destination file's current text ("" if it does not exist)
+ * @param desired   the permissions and/or plugins state Praxis wants to own
+ */
+export declare function reconcileSettings(existing: string, desired: DesiredSettings): JsonReconcileResult;
+/** Permissions-only convenience wrapper over `reconcileSettings` — kept because
+ *  most call sites and tests only ever reconcile permissions. */
+export declare function reconcilePermissions(existing: string, desired: RuleSet): JsonReconcileResult;