@aacombarro89/praxis 0.1.0

package/dist/merge-json.js

@@ -0,0 +1,207 @@
+/**
+ * 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 const BUCKETS = ["allow", "ask", "deny"];
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * 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 function reconcileSettings(existing, desired) {
+    const root = parseRoot(existing);
+    const marker = isObject(root._praxis) ? root._praxis : {};
+    const managed = marker.managed ?? {};
+    const conflicts = [];
+    const newManaged = {};
+    if (desired.permissions) {
+        const recorded = managed.permissions ?? {};
+        const permissions = isObject(root.permissions)
+            ? root.permissions
+            : {};
+        const newRecorded = {};
+        for (const bucket of BUCKETS) {
+            const onDisk = asStringArray(permissions[bucket]);
+            const rec = asStringArray(recorded[bucket]);
+            const want = desired.permissions[bucket] ?? [];
+            // Conflict, never clobber (D10): the managed set is intact only if every
+            // rule Praxis last emitted is still present.
+            const intact = rec.every((r) => onDisk.includes(r));
+            if (!intact) {
+                conflicts.push(`permissions.${bucket}`);
+                newRecorded[bucket] = rec;
+                continue;
+            }
+            const recSet = new Set(rec);
+            const wantSet = new Set(want);
+            const merged = [];
+            for (const r of onDisk) {
+                if (!recSet.has(r) || wantSet.has(r))
+                    merged.push(r);
+            }
+            for (const r of want) {
+                if (!merged.includes(r))
+                    merged.push(r);
+            }
+            if (merged.length > 0)
+                permissions[bucket] = merged;
+            else
+                delete permissions[bucket];
+            if (want.length > 0)
+                newRecorded[bucket] = want;
+        }
+        if (Object.keys(permissions).length > 0)
+            root.permissions = permissions;
+        else
+            delete root.permissions;
+        if (Object.keys(newRecorded).length > 0)
+            newManaged.permissions = newRecorded;
+    }
+    else if (managed.permissions) {
+        // Not part of this sync — keep tracking what we previously owned untouched.
+        newManaged.permissions = managed.permissions;
+    }
+    if (desired.plugins) {
+        const recordedMarketplaces = managed.marketplaces ?? [];
+        const recordedPlugins = managed.plugins ?? [];
+        const marketplaces = isObject(root.extraKnownMarketplaces)
+            ? root.extraKnownMarketplaces
+            : {};
+        const enabledPlugins = isObject(root.enabledPlugins)
+            ? root.enabledPlugins
+            : {};
+        const marketplacesIntact = recordedMarketplaces.every((name) => name in marketplaces);
+        const pluginsIntact = recordedPlugins.every((key) => key in enabledPlugins);
+        if (!marketplacesIntact) {
+            // Conflict, never clobber (D10): leave extraKnownMarketplaces exactly as
+            // found on disk (including a present-but-empty `{}`), don't recompute it.
+            conflicts.push("plugins.marketplaces");
+            newManaged.marketplaces = recordedMarketplaces;
+        }
+        else {
+            const wantNames = new Set(desired.plugins.marketplaces.map((m) => m.name));
+            for (const name of Object.keys(marketplaces)) {
+                if (recordedMarketplaces.includes(name) && !wantNames.has(name))
+                    delete marketplaces[name];
+            }
+            for (const m of desired.plugins.marketplaces) {
+                marketplaces[m.name] = { source: m.source };
+            }
+            if (Object.keys(marketplaces).length > 0)
+                root.extraKnownMarketplaces = marketplaces;
+            else
+                delete root.extraKnownMarketplaces;
+            if (desired.plugins.marketplaces.length > 0) {
+                newManaged.marketplaces = desired.plugins.marketplaces.map((m) => m.name);
+            }
+        }
+        if (!pluginsIntact) {
+            // Same conflict rule for enabledPlugins, independently of marketplaces.
+            conflicts.push("plugins.enable");
+            newManaged.plugins = recordedPlugins;
+        }
+        else {
+            const wantKeys = new Set(desired.plugins.enable);
+            for (const key of Object.keys(enabledPlugins)) {
+                if (recordedPlugins.includes(key) && !wantKeys.has(key))
+                    delete enabledPlugins[key];
+            }
+            for (const key of desired.plugins.enable) {
+                enabledPlugins[key] = true;
+            }
+            if (Object.keys(enabledPlugins).length > 0)
+                root.enabledPlugins = enabledPlugins;
+            else
+                delete root.enabledPlugins;
+            if (desired.plugins.enable.length > 0)
+                newManaged.plugins = desired.plugins.enable;
+        }
+    }
+    else {
+        if (managed.marketplaces)
+            newManaged.marketplaces = managed.marketplaces;
+        if (managed.plugins)
+            newManaged.plugins = managed.plugins;
+    }
+    if (Object.keys(newManaged).length > 0) {
+        root._praxis = { managed: newManaged };
+    }
+    else {
+        delete root._praxis;
+    }
+    const text = `${JSON.stringify(root, null, 2)}\n`;
+    return { text, changed: text !== normalize(existing), conflicts };
+}
+/** Permissions-only convenience wrapper over `reconcileSettings` — kept because
+ *  most call sites and tests only ever reconcile permissions. */
+export function reconcilePermissions(existing, desired) {
+    return reconcileSettings(existing, { permissions: desired });
+}
+/** Parse the host file into a mutable object, preserving key order. Empty/blank
+ *  → `{}`. Invalid JSON throws a readable error rather than risk a clobber. */
+function parseRoot(existing) {
+    if (existing.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(existing);
+    }
+    catch (err) {
+        throw new Error(`Cannot merge settings: the destination file is not valid JSON ` +
+            `(${err.message}). Fix or remove it, then re-run \`praxis sync\`.`);
+    }
+    if (!isObject(parsed)) {
+        throw new Error(`Cannot merge settings: the destination file must be a JSON object, ` +
+            `got ${Array.isArray(parsed) ? "an array" : typeof parsed}.`);
+    }
+    return parsed;
+}
+/** The byte-form a no-op write would produce for the given input, used to compute
+ *  `changed` honestly when the input is already-formatted JSON. */
+function normalize(existing) {
+    if (existing.trim() === "")
+        return "";
+    try {
+        return `${JSON.stringify(JSON.parse(existing), null, 2)}\n`;
+    }
+    catch {
+        return existing;
+    }
+}
+//# sourceMappingURL=merge-json.js.map

package/dist/merge-json.js.map

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

package/dist/merge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The block-splice merge core (docs/wiki/merge-engine.md, decisions D7/D10/D11).
+ *
+ * Praxis owns only the text between its `praxis:begin`/`praxis:end` markers.
+ * The host file is never parsed as markdown — we locate our own machine markers
+ * and treat the content between them as OPAQUE text. This is the whole point of
+ * rejecting a markdown AST (D7): re-serializing a tree would normalize the user's
+ * prose. Here, every byte outside a managed span is preserved exactly.
+ */
+/** A Praxis-managed region located in a host file. */
+export interface ManagedBlock {
+    id: string;
+    /** Exact bytes between the markers, excluding the marker lines. Opaque. */
+    content: string;
+    /** sha256 recorded in the begin marker (`""` if the marker carried none). */
+    recordedHash: string;
+    /** Offset of the block start (begin marker) in the source text. */
+    start: number;
+    /** Offset just past the end marker in the source text. */
+    end: number;
+}
+export type BlockStatus = "absent" | "unchanged" | "user-edited";
+/** sha256 (hex) of the content. Used to detect user edits inside a block. */
+export declare function hashContent(content: string): string;
+/** Render a full managed block, stamping the begin marker with a fresh hash. */
+export declare function renderBlock(id: string, content: string): string;
+/** All managed blocks in the text, in document order. */
+export declare function findBlocks(text: string): ManagedBlock[];
+/** The first managed block with the given id, wherever it sits in the file. */
+export declare function findBlock(text: string, id: string): ManagedBlock | undefined;
+/**
+ * absent       — no such block in the file.
+ * unchanged    — on-disk content still matches the recorded hash (Praxis's last
+ *                emission is intact; safe to update).
+ * user-edited  — on-disk content differs from the recorded hash; the user (or
+ *                agent) edited managed content. Never overwrite (D10).
+ */
+export declare function blockStatus(block: ManagedBlock | undefined): BlockStatus;
+export interface ReconcileResult {
+    /** The resulting file text. */
+    text: string;
+    /** Whether any byte changed. */
+    changed: boolean;
+    /** Ids of blocks the user edited; left untouched, surfaced for resolution. */
+    conflicts: string[];
+}
+/**
+ * Bring the host text in line with the desired managed content, one block per
+ * entry of `desired` (id -> content). Splices only managed spans; appends blocks
+ * that are absent; refuses to overwrite blocks the user has edited (conflict).
+ * Idempotent: reconciling with already-applied content is a byte-for-byte no-op.
+ */
+export declare function reconcile(text: string, desired: Record<string, string>): ReconcileResult;

package/dist/merge.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+const beginMarker = (id, hash) => `<!-- praxis:begin ${id} sha256=${hash} (managed by praxis - edit praxis.yaml then run: praxis sync) -->`;
+const endMarker = (id) => `<!-- praxis:end ${id} -->`;
+// Match our own fences only. Group 1: id. Group 2: begin-marker attributes
+// (carries sha256). Group 3: opaque content. The id backreference (\1) ties the
+// end marker to its begin marker; content is non-greedy so the nearest end wins.
+const BLOCK_RE = /<!--\s*praxis:begin\s+([A-Za-z0-9._-]+)([^>]*?)-->[^\n]*\r?\n([\s\S]*?)\r?\n?<!--\s*praxis:end\s+\1\s*-->/g;
+function extractHash(attrs) {
+    const m = /sha256=([A-Za-z0-9]+)/.exec(attrs);
+    return m?.[1] ?? "";
+}
+/** sha256 (hex) of the content. Used to detect user edits inside a block. */
+export function hashContent(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** Render a full managed block, stamping the begin marker with a fresh hash. */
+export function renderBlock(id, content) {
+    return `${beginMarker(id, hashContent(content))}\n${content}\n${endMarker(id)}`;
+}
+/** All managed blocks in the text, in document order. */
+export function findBlocks(text) {
+    const blocks = [];
+    BLOCK_RE.lastIndex = 0;
+    let m;
+    while ((m = BLOCK_RE.exec(text)) !== null) {
+        blocks.push({
+            id: m[1] ?? "",
+            recordedHash: extractHash(m[2] ?? ""),
+            content: m[3] ?? "",
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+    }
+    return blocks;
+}
+/** The first managed block with the given id, wherever it sits in the file. */
+export function findBlock(text, id) {
+    return findBlocks(text).find((b) => b.id === id);
+}
+/**
+ * absent       — no such block in the file.
+ * unchanged    — on-disk content still matches the recorded hash (Praxis's last
+ *                emission is intact; safe to update).
+ * user-edited  — on-disk content differs from the recorded hash; the user (or
+ *                agent) edited managed content. Never overwrite (D10).
+ */
+export function blockStatus(block) {
+    if (!block)
+        return "absent";
+    return block.recordedHash === hashContent(block.content)
+        ? "unchanged"
+        : "user-edited";
+}
+/**
+ * Bring the host text in line with the desired managed content, one block per
+ * entry of `desired` (id -> content). Splices only managed spans; appends blocks
+ * that are absent; refuses to overwrite blocks the user has edited (conflict).
+ * Idempotent: reconciling with already-applied content is a byte-for-byte no-op.
+ */
+export function reconcile(text, desired) {
+    let out = text;
+    let changed = false;
+    const conflicts = [];
+    for (const [id, content] of Object.entries(desired)) {
+        const block = findBlock(out, id);
+        if (!block) {
+            out = appendBlock(out, id, content);
+            changed = true;
+            continue;
+        }
+        if (blockStatus(block) === "user-edited") {
+            conflicts.push(id);
+            continue; // never clobber a user edit (D10)
+        }
+        if (block.content !== content) {
+            out = out.slice(0, block.start) + renderBlock(id, content) + out.slice(block.end);
+            changed = true;
+        }
+    }
+    return { text: out, changed, conflicts };
+}
+function appendBlock(text, id, content) {
+    const block = renderBlock(id, content);
+    if (text.length === 0)
+        return `${block}\n`;
+    const sep = text.endsWith("\n") ? "\n" : "\n\n";
+    return `${text}${sep}${block}\n`;
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2BzC,MAAM,WAAW,GAAG,CAAC,EAAU,EAAE,IAAY,EAAU,EAAE,CACvD,qBAAqB,EAAE,WAAW,IAAI,mEAAmE,CAAC;AAE5G,MAAM,SAAS,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,mBAAmB,EAAE,MAAM,CAAC;AAEtE,2EAA2E;AAC3E,gFAAgF;AAChF,iFAAiF;AACjF,MAAM,QAAQ,GACZ,4GAA4G,CAAC;AAE/G,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,OAAe;IACrD,OAAO,GAAG,WAAW,CAAC,EAAE,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,KAAK,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC;IACvB,IAAI,CAAyB,CAAC;IAC9B,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YACd,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACrC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YACnB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;SAC3B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,EAAU;IAChD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAA+B;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,OAAO,KAAK,CAAC,YAAY,KAAK,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC;QACtD,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,aAAa,CAAC;AACpB,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,IAAY,EACZ,OAA+B;IAE/B,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAEjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,aAAa,EAAE,CAAC;YACzC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,SAAS,CAAC,kCAAkC;QAC9C,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC9B,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAClF,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,EAAU,EAAE,OAAe;IAC5D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,KAAK,IAAI,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,GAAG,IAAI,GAAG,GAAG,GAAG,KAAK,IAAI,CAAC;AACnC,CAAC"}

package/dist/packages.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+declare const ARTIFACTS: readonly ["rules", "permissions", "commands", "plugins"];
+export type Artifact = (typeof ARTIFACTS)[number];
+export declare const packageManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    layer: z.ZodEnum<{
+        layer1: "layer1";
+        layer2: "layer2";
+        decision: "decision";
+        external: "external";
+    }>;
+    provides: z.ZodArray<z.ZodEnum<{
+        rules: "rules";
+        permissions: "permissions";
+        commands: "commands";
+        plugins: "plugins";
+    }>>;
+    requires: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    conflicts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    stack: z.ZodOptional<z.ZodEnum<{
+        "python-backend": "python-backend";
+        node: "node";
+        react: "react";
+    }>>;
+}, z.core.$strict>;
+export type PackageManifest = z.infer<typeof packageManifestSchema>;
+export interface ResolvedPackage extends PackageManifest {
+    /** Absolute path to the package directory (where its artifacts live). */
+    dir: string;
+}
+/** Parse + validate a `package.yaml`. `dirName` is the directory the file was
+ *  found in; the declared `name` must match it. */
+export declare function parsePackageManifest(yamlText: string, dirName: string): PackageManifest;
+/** Every installed package, keyed by name. Scans `packages/<layer>/<pkg>/package.yaml`. */
+export declare function availablePackages(): Map<string, ResolvedPackage>;
+/**
+ * Resolve the selected package names against what's available, enforcing the
+ * composition rule (docs/wiki/packages-and-emit.md): every name must exist, every `requires` must also be
+ * selected, no two selected packages may `conflict`, and a package targeting a
+ * stack is only valid when the repo declares that stack. Pure — `available` and
+ * `declaredStacks` are injected so the logic is testable without the filesystem.
+ * Throws an agent-actionable error on the first problem.
+ */
+export declare function resolve(selected: string[], available: Map<string, ResolvedPackage>, declaredStacks?: string[]): ResolvedPackage[];
+/** Resolve the selected packages against the installed set (filesystem-backed). */
+export declare function resolvePackages(selected: string[], declaredStacks?: string[]): ResolvedPackage[];
+export {};

package/dist/packages.js

@@ -0,0 +1,121 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { STACKS } from "./manifest.js";
+/**
+ * The package loader (docs/wiki/packages-and-emit.md, decisions D20/D21). Each package carries
+ * a `package.yaml` declaring what it is and **provides**; the loader discovers all
+ * installed packages, validates the set selected in `praxis.yaml`, and resolves
+ * `requires`/`conflicts`.
+ *
+ * This replaces filesystem *probing* (try to load each artifact, keep what isn't
+ * undefined) with a *declared* contract: a package says what it provides, and an
+ * unknown package name fails loudly rather than emitting nothing (D4's "typos
+ * fail loud", extended to packages).
+ */
+const PACKAGES_DIR = new URL("../packages/", import.meta.url);
+// What a package can contribute. Closed vocabulary; each maps to an emitter path.
+const ARTIFACTS = ["rules", "permissions", "commands", "plugins"];
+// "external" holds thin packages that declare a Claude Code plugin marketplace
+// (packages/external/<pkg>/) rather than authoring methodology content directly.
+const LAYERS = ["layer1", "layer2", "decision", "external"];
+export const packageManifestSchema = z.strictObject({
+    name: z.string().min(1),
+    layer: z.enum(LAYERS),
+    provides: z.array(z.enum(ARTIFACTS)).min(1),
+    requires: z.array(z.string().min(1)).default([]),
+    conflicts: z.array(z.string().min(1)).default([]),
+    // Layer 2 packages declare the stack they target; a repo only gets them when it
+    // declares that stack in praxis.yaml `stacks`. Layer 1 / external packages omit it.
+    stack: z.enum(STACKS).optional(),
+});
+/** Parse + validate a `package.yaml`. `dirName` is the directory the file was
+ *  found in; the declared `name` must match it. */
+export function parsePackageManifest(yamlText, dirName) {
+    let raw;
+    try {
+        raw = parseYaml(yamlText);
+    }
+    catch (err) {
+        throw new Error(`package.yaml in "${dirName}" is not valid YAML: ${err.message}`);
+    }
+    const result = packageManifestSchema.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(`package.yaml in "${dirName}" is invalid:\n${issues}`);
+    }
+    if (result.data.name !== dirName) {
+        throw new Error(`package.yaml name "${result.data.name}" must match its directory "${dirName}".`);
+    }
+    return result.data;
+}
+/** Every installed package, keyed by name. Scans `packages/<layer>/<pkg>/package.yaml`. */
+export function availablePackages() {
+    const root = fileURLToPath(PACKAGES_DIR);
+    const out = new Map();
+    for (const layer of readdirSync(root, { withFileTypes: true })) {
+        if (!layer.isDirectory())
+            continue;
+        const layerDir = join(root, layer.name);
+        for (const pkg of readdirSync(layerDir, { withFileTypes: true })) {
+            if (!pkg.isDirectory())
+                continue;
+            const dir = join(layerDir, pkg.name);
+            const manifestPath = join(dir, "package.yaml");
+            if (!existsSync(manifestPath))
+                continue; // a directory without a manifest is not a package
+            const manifest = parsePackageManifest(readFileSync(manifestPath, "utf8"), pkg.name);
+            out.set(manifest.name, { ...manifest, dir });
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the selected package names against what's available, enforcing the
+ * composition rule (docs/wiki/packages-and-emit.md): every name must exist, every `requires` must also be
+ * selected, no two selected packages may `conflict`, and a package targeting a
+ * stack is only valid when the repo declares that stack. Pure — `available` and
+ * `declaredStacks` are injected so the logic is testable without the filesystem.
+ * Throws an agent-actionable error on the first problem.
+ */
+export function resolve(selected, available, declaredStacks = []) {
+    const resolved = selected.map((name) => {
+        const pkg = available.get(name);
+        if (!pkg) {
+            throw new Error(`praxis.yaml lists package "${name}" but no such package is installed.\n` +
+                `Available packages: ${[...available.keys()].sort().join(", ") || "(none)"}.`);
+        }
+        return pkg;
+    });
+    const selectedSet = new Set(selected);
+    const stackSet = new Set(declaredStacks);
+    for (const pkg of resolved) {
+        if (pkg.stack && !stackSet.has(pkg.stack)) {
+            throw new Error(`Package "${pkg.name}" targets the "${pkg.stack}" stack, which praxis.yaml does not declare.\n` +
+                `Add "${pkg.stack}" to \`stacks\` in praxis.yaml, or remove the package — a Layer 2 ` +
+                `recipe applies only when its stack is wanted (D15).`);
+        }
+        for (const req of pkg.requires) {
+            if (!selectedSet.has(req)) {
+                throw new Error(`Package "${pkg.name}" requires "${req}", which is not in praxis.yaml.\n` +
+                    `Add "${req}" to packages — a rule without its required support is broken (D21).`);
+            }
+        }
+        for (const con of pkg.conflicts) {
+            if (selectedSet.has(con)) {
+                throw new Error(`Packages "${pkg.name}" and "${con}" conflict and cannot be installed together.\n` +
+                    `Remove one from praxis.yaml.`);
+            }
+        }
+    }
+    return resolved;
+}
+/** Resolve the selected packages against the installed set (filesystem-backed). */
+export function resolvePackages(selected, declaredStacks = []) {
+    return resolve(selected, availablePackages(), declaredStacks);
+}
+//# sourceMappingURL=packages.js.map

package/dist/packages.js.map

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

package/dist/permissions.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+declare const CAPABILITIES: readonly ["read-repo", "edit-repo", "run-dev-scripts", "read-only-git", "git-commit", "git-push", "install-deps", "destructive-delete", "force-push", "read-secrets", "global-install"];
+export type Capability = (typeof CAPABILITIES)[number];
+export declare const policySchema: z.ZodObject<{
+    allow: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "read-repo": "read-repo";
+        "edit-repo": "edit-repo";
+        "run-dev-scripts": "run-dev-scripts";
+        "read-only-git": "read-only-git";
+        "git-commit": "git-commit";
+        "git-push": "git-push";
+        "install-deps": "install-deps";
+        "destructive-delete": "destructive-delete";
+        "force-push": "force-push";
+        "read-secrets": "read-secrets";
+        "global-install": "global-install";
+    }>>>;
+    ask: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "read-repo": "read-repo";
+        "edit-repo": "edit-repo";
+        "run-dev-scripts": "run-dev-scripts";
+        "read-only-git": "read-only-git";
+        "git-commit": "git-commit";
+        "git-push": "git-push";
+        "install-deps": "install-deps";
+        "destructive-delete": "destructive-delete";
+        "force-push": "force-push";
+        "read-secrets": "read-secrets";
+        "global-install": "global-install";
+    }>>>;
+    deny: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "read-repo": "read-repo";
+        "edit-repo": "edit-repo";
+        "run-dev-scripts": "run-dev-scripts";
+        "read-only-git": "read-only-git";
+        "git-commit": "git-commit";
+        "git-push": "git-push";
+        "install-deps": "install-deps";
+        "destructive-delete": "destructive-delete";
+        "force-push": "force-push";
+        "read-secrets": "read-secrets";
+        "global-install": "global-install";
+    }>>>;
+}, z.core.$strict>;
+export type Policy = z.infer<typeof policySchema>;
+/** Parse + validate neutral policy text. Throws a readable, agent-actionable
+ *  error naming each problem — mirrors parseManifest in src/manifest.ts. */
+export declare function parsePolicy(yamlText: string): Policy;
+/** The neutral policy for a content package, or undefined if it provides none.
+ *  Scans packages/<layer>/<pkg>/permissions.yaml — mirrors loadPackageSource. */
+export declare function loadPolicy(pkg: string): Policy | undefined;
+/** All capabilities referenced by a policy, across every bucket. */
+export declare function policyCapabilities(policy: Policy): Capability[];
+export {};