@baselane/materialize 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+Copyright 2026 Mohammad Omar
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,15 @@
+# @baselane/materialize
+
+Disk-reconcile and install engine (plan/apply/receipt/settings-merge/manifest-io/resolve/
+install) shared by the [`baselane`](https://www.npmjs.com/package/baselane) CLI and the
+baselane desktop agent.
+
+## Install
+
+```sh
+npm install @baselane/materialize
+```
+
+Used as a library dependency of `baselane` — most users won't install it directly.
+
+Docs: https://baselane.sh

package/dist/fs-ops.d.ts

@@ -0,0 +1,6 @@
+import type { Bundle, Manifest, ReconcilePlan } from "./types.ts";
+export declare const MANIFEST_NAME = ".baselane-manifest.json";
+export declare function loadManifest(rootDir: string): Promise<Manifest>;
+export declare function readCurrent(rootDir: string, paths: string[]): Promise<Record<string, string | null>>;
+export declare function applyPlan(rootDir: string, bundle: Bundle, plan: ReconcilePlan): Promise<void>;
+export declare function writeManifest(rootDir: string, bundle: Bundle): Promise<void>;

package/dist/fs-ops.js

@@ -0,0 +1,101 @@
+import { lstat, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { sha256 } from "./hash.js";
+export const MANIFEST_NAME = ".baselane-manifest.json";
+// Lexical containment only — symlink traversal is refused separately by assertNoSymlinkWithin on mutating ops.
+function resolveInside(rootDir, path) {
+    const abs = resolve(rootDir, path);
+    const rootAbs = resolve(rootDir);
+    if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) {
+        throw new Error(`baselane: path "${path}" escapes target root`);
+    }
+    return abs;
+}
+async function assertNoSymlinkWithin(rootDir, relPath) {
+    const segments = relPath.split("/");
+    let current = resolve(rootDir);
+    for (const segment of segments) {
+        current = join(current, segment);
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return; // remainder doesn't exist yet; mkdir creates real dirs
+            throw err;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new Error(`baselane: path "${relPath}" traverses a symlink ("${segment}") — refusing`);
+        }
+    }
+}
+async function readIfExists(absPath) {
+    try {
+        return await readFile(absPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw err;
+    }
+}
+export async function loadManifest(rootDir) {
+    const raw = await readIfExists(join(rootDir, MANIFEST_NAME));
+    if (raw === null)
+        return { version: 1, files: {} };
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1 || typeof parsed.files !== "object" || parsed.files === null) {
+        throw new Error("baselane: malformed manifest");
+    }
+    return parsed;
+}
+export async function readCurrent(rootDir, paths) {
+    const state = {};
+    for (const path of paths) {
+        state[path] = await readIfExists(resolveInside(rootDir, path));
+    }
+    return state;
+}
+export async function applyPlan(rootDir, bundle, plan) {
+    // A file in plan.drifted was hand-edited since baselane last wrote it. It is also in
+    // plan.writes (its content differs from desired), so applyPlan is about to overwrite —
+    // revert — the local edit. Back the local version up to <path>.baselane-bak FIRST so a
+    // developer's edit is never silently lost (#3 data-loss critical: revert-without-backup).
+    const drifted = new Set(plan.drifted);
+    for (const path of plan.writes) {
+        await assertNoSymlinkWithin(rootDir, path);
+        const abs = resolveInside(rootDir, path);
+        const content = bundle.files[path];
+        if (content === undefined)
+            throw new Error(`baselane: write "${path}" not in bundle`);
+        if (drifted.has(path)) {
+            const local = await readFile(abs, "utf8").catch(() => null);
+            if (local !== null)
+                await writeFile(`${abs}.baselane-bak`, local, "utf8");
+        }
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, "utf8");
+    }
+    for (const path of plan.deletes) {
+        await assertNoSymlinkWithin(rootDir, path);
+        const abs = resolveInside(rootDir, path);
+        // Same rule as writes: a delete target that's drifted (hand-edited since baselane last wrote
+        // it) is about to lose that edit permanently. Back it up first.
+        if (drifted.has(path)) {
+            const local = await readFile(abs, "utf8").catch(() => null);
+            if (local !== null)
+                await writeFile(`${abs}.baselane-bak`, local, "utf8");
+        }
+        await unlink(abs);
+    }
+}
+export async function writeManifest(rootDir, bundle) {
+    const manifest = {
+        version: 1,
+        files: Object.fromEntries(Object.entries(bundle.files).map(([path, content]) => [path, sha256(content)])),
+    };
+    await writeFile(join(rootDir, MANIFEST_NAME), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}

package/dist/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256(content: string): string;

package/dist/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { sha256 } from "./hash.ts";
+export { planReconcile } from "./plan.ts";
+export { applyPlan, loadManifest, readCurrent, writeManifest, MANIFEST_NAME } from "./fs-ops.ts";
+export { hasManagedHooks, mergeBaselaneHooks, SettingsParseError } from "./settings-merge.ts";
+export type { Bundle, BundleOnboardingStep, Manifest, ReconcilePlan } from "./types.ts";
+export { targetLocation, readManifestFile, readManifestWithFallback, writeManifestFile } from "./manifest-io.ts";
+export type { TargetLocation } from "./manifest-io.ts";
+export { resolveManifestPacks, fetchRegistryVersions, registryBaseFor, encodeSkillPin, decodeSkillPin, DEFAULT_REGISTRY } from "./resolve-packs.ts";
+export type { ResolvedManifestPacks, RegistryVersionEntry } from "./resolve-packs.ts";
+export { runInstall, installFromManifest } from "./install.ts";
+export type { InstallOptions, InstallReport } from "./install.ts";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { sha256 } from "./hash.js";
+export { planReconcile } from "./plan.js";
+export { applyPlan, loadManifest, readCurrent, writeManifest, MANIFEST_NAME } from "./fs-ops.js";
+export { hasManagedHooks, mergeBaselaneHooks, SettingsParseError } from "./settings-merge.js";
+export { targetLocation, readManifestFile, readManifestWithFallback, writeManifestFile } from "./manifest-io.js";
+export { resolveManifestPacks, fetchRegistryVersions, registryBaseFor, encodeSkillPin, decodeSkillPin, DEFAULT_REGISTRY } from "./resolve-packs.js";
+export { runInstall, installFromManifest } from "./install.js";

package/dist/install.d.ts

@@ -0,0 +1,35 @@
+import { type HarnessManifest, type WorkflowPack } from "@baselane/packs";
+import { type TargetLocation } from "./manifest-io.ts";
+export interface InstallOptions {
+    source?: string;
+    global: boolean;
+    dir?: string;
+    homeDir?: string;
+    dryRun: boolean;
+    json: boolean;
+    token?: string;
+    fetchImpl?: typeof fetch;
+    registryBase?: string;
+    log?: (line: string) => void;
+}
+export interface InstallReport {
+    manifestPath: string;
+    targetDir: string;
+    packs: Record<string, string>;
+    writes: string[];
+    deletes: string[];
+    driftedBackedUp: string[];
+    unchanged: string[];
+    notes: string[];
+    dryRun: boolean;
+}
+export declare function installFromManifest(manifest: HarnessManifest, loc: TargetLocation, opts: {
+    dryRun: boolean;
+    token?: string;
+    fetchImpl?: typeof fetch;
+    registryBase?: string;
+    log?: (l: string) => void;
+    inlinePacks?: Record<string, WorkflowPack>;
+    priorReceipt?: Record<string, string>;
+}, prior: HarnessManifest | null): Promise<InstallReport>;
+export declare function runInstall(opts: InstallOptions): Promise<InstallReport>;

package/dist/install.js

@@ -0,0 +1,115 @@
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildManifest, materializeHarness, ENTRY_FILES, LEGACY_MANIFEST_PATH, MANIFEST_PATH, } from "@baselane/packs";
+import { parseInstallRef, resolveDefaultBranch } from "@baselane/distribute";
+import { applyPlan, readCurrent } from "./fs-ops.js";
+import { planReconcile } from "./plan.js";
+import { mergeBaselaneHooks, SettingsParseError } from "./settings-merge.js";
+import { readManifestWithFallback, targetLocation, writeManifestFile } from "./manifest-io.js";
+import { DEFAULT_REGISTRY, encodeSkillPin, fetchRegistryVersions, resolveManifestPacks } from "./resolve-packs.js";
+const MACHINE_SETTINGS_PATH = "settings.json";
+export async function installFromManifest(manifest, loc, opts, prior) {
+    const log = opts.log ?? console.log;
+    const notes = [];
+    const { packs, resolutions } = await resolveManifestPacks(manifest, {
+        token: opts.token, fetchImpl: opts.fetchImpl, inlinePacks: opts.inlinePacks, registryBase: opts.registryBase,
+        onNotice: (m) => { notes.push(m); log(m); },
+    }).then((r) => { notes.push(...r.notes); r.notes.forEach(log); return r; });
+    const entryState = await readCurrent(loc.targetDir, [...ENTRY_FILES]);
+    const result = materializeHarness({ manifest, resolvedPacks: packs, currentFiles: entryState, resolutions });
+    const desired = { ...result.files };
+    let heldSettings = null;
+    if (loc.target.kind === "machine" && desired[MACHINE_SETTINGS_PATH] !== undefined) {
+        heldSettings = desired[MACHINE_SETTINGS_PATH];
+        delete desired[MACHINE_SETTINGS_PATH];
+    }
+    const bundle = { version: 1, files: desired };
+    const receipt = {
+        version: 1,
+        files: opts.priorReceipt ??
+            Object.fromEntries((prior?.materialized.vendored ?? [])
+                .filter((v) => v.sha256 !== null)
+                .map((v) => [v.path, v.sha256])),
+    };
+    const onDisk = await readCurrent(loc.targetDir, [...new Set([...Object.keys(desired), ...Object.keys(receipt.files)])]);
+    const plan = planReconcile(bundle, receipt, onDisk);
+    const report = {
+        manifestPath: loc.manifestPath, targetDir: loc.targetDir,
+        packs: manifest.packs,
+        writes: plan.writes, deletes: plan.deletes,
+        driftedBackedUp: plan.drifted.filter((p) => plan.writes.includes(p) || plan.deletes.includes(p)),
+        unchanged: plan.unchanged, notes, dryRun: opts.dryRun,
+    };
+    if (opts.dryRun)
+        return report;
+    await applyPlan(loc.targetDir, bundle, plan);
+    if (heldSettings !== null) {
+        const settingsPath = join(loc.targetDir, MACHINE_SETTINGS_PATH);
+        let current;
+        try {
+            current = await readFile(settingsPath, "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                current = null;
+            else
+                throw err; // e.g. EACCES — do NOT silently treat an unreadable file as absent (clobber risk)
+        }
+        try {
+            await writeFile(settingsPath, mergeBaselaneHooks(current, heldSettings), "utf8");
+        }
+        catch (err) {
+            if (err instanceof SettingsParseError) {
+                throw new Error(`install: ${settingsPath} is not valid JSON — fix or remove it, then re-run (refusing to overwrite)`);
+            }
+            throw err;
+        }
+    }
+    await writeManifestFile(loc.manifestPath, result.manifest);
+    return report;
+}
+export async function runInstall(opts) {
+    const log = opts.log ?? console.log;
+    const loc = targetLocation({ global: opts.global, dir: opts.dir, homeDir: opts.homeDir });
+    const { manifest: existing, legacyPath } = await readManifestWithFallback(loc);
+    const base = existing ?? buildManifest({ target: loc.target, packs: {} });
+    let manifest = base;
+    if (opts.source !== undefined) {
+        const parsed = parseInstallRef(opts.source);
+        if (parsed.kind === "git") {
+            manifest = { ...base, packs: { ...base.packs, [parsed.name]: parsed.ref } };
+        }
+        else if (parsed.kind === "registry") {
+            const registryBase = base.registry ?? opts.registryBase ?? DEFAULT_REGISTRY;
+            let version = parsed.version;
+            if (version === null) {
+                const versions = await fetchRegistryVersions(parsed.name, registryBase, { fetchImpl: opts.fetchImpl, onNotice: log });
+                if (versions.length === 0)
+                    throw new Error(`install: "${parsed.name}" has no published versions at ${registryBase}`);
+                version = versions[0].version; // fetchRegistryVersions sorts semver-desc locally — index 0 is the true latest
+            }
+            manifest = { ...base, packs: { ...base.packs, [parsed.name]: version } };
+        }
+        else {
+            // "skill": owner/repo@skill — no explicit ref, so pin at the repo's default branch;
+            // the single-skill filter rides along in the pin (see encodeSkillPin's doc comment).
+            const label = `${parsed.owner}/${parsed.repo}`;
+            const branch = await resolveDefaultBranch(parsed.owner, parsed.repo, { token: opts.token, fetchImpl: opts.fetchImpl ?? fetch, label });
+            const gitName = `github:${parsed.owner}/${parsed.repo}`;
+            manifest = { ...base, packs: { ...base.packs, [gitName]: encodeSkillPin(branch, parsed.skill) } };
+        }
+    }
+    if (Object.keys(manifest.packs).length === 0 && opts.source === undefined && existing === null) {
+        throw new Error(`install: no ${loc.manifestPath} found and no source given — nothing to install`);
+    }
+    const report = await installFromManifest(manifest, loc, { dryRun: opts.dryRun, token: opts.token, fetchImpl: opts.fetchImpl, registryBase: opts.registryBase, log }, existing);
+    // Legacy .baselane/harness.json is superseded by the just-written root manifest — remove it
+    // only once the new one is confirmed on disk (dry-run never reaches here with legacyPath set
+    // as a real migration, since nothing was written).
+    if (legacyPath !== null && !opts.dryRun) {
+        await unlink(legacyPath);
+        log(`migrated manifest: ${LEGACY_MANIFEST_PATH} → ${MANIFEST_PATH}`);
+    }
+    return report;
+}

package/dist/manifest-io.d.ts

@@ -0,0 +1,25 @@
+import { type HarnessManifest } from "@baselane/packs";
+export interface TargetLocation {
+    manifestPath: string;
+    targetDir: string;
+    target: {
+        kind: "repo" | "machine";
+        id: string;
+    };
+}
+export declare function targetLocation(opts: {
+    global: boolean;
+    dir?: string;
+    homeDir?: string;
+}): TargetLocation;
+export declare function readManifestFile(manifestPath: string): Promise<HarnessManifest | null>;
+/** Reads a target's manifest, falling back to the pre-2026-07-16 `.baselane/harness.json`
+ * location for repo targets when the root manifest is absent. Machine targets never fall
+ * back — `loc.manifestPath` (`~/.baselane/harness.json`) is unchanged and has no legacy path.
+ * `legacyPath` is non-null only when the fallback was actually used, signaling callers that
+ * migrated on write (see `installFromManifest`). */
+export declare function readManifestWithFallback(loc: TargetLocation): Promise<{
+    manifest: HarnessManifest | null;
+    legacyPath: string | null;
+}>;
+export declare function writeManifestFile(manifestPath: string, manifest: HarnessManifest): Promise<void>;

package/dist/manifest-io.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { hostname, homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { LEGACY_MANIFEST_PATH, MANIFEST_PATH, validateManifest } from "@baselane/packs";
+export function targetLocation(opts) {
+    if (opts.global) {
+        const home = opts.homeDir ?? homedir();
+        return {
+            manifestPath: join(home, ".baselane", "harness.json"),
+            targetDir: opts.dir ?? join(home, ".claude"),
+            target: { kind: "machine", id: hostname() },
+        };
+    }
+    const dir = resolve(opts.dir ?? ".");
+    return {
+        manifestPath: join(dir, MANIFEST_PATH),
+        targetDir: dir,
+        target: { kind: "repo", id: basename(dir) },
+    };
+}
+export async function readManifestFile(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw err;
+    }
+    try {
+        return validateManifest(JSON.parse(raw));
+    }
+    catch (err) {
+        throw new Error(`harness.json at ${manifestPath} is invalid: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Reads a target's manifest, falling back to the pre-2026-07-16 `.baselane/harness.json`
+ * location for repo targets when the root manifest is absent. Machine targets never fall
+ * back — `loc.manifestPath` (`~/.baselane/harness.json`) is unchanged and has no legacy path.
+ * `legacyPath` is non-null only when the fallback was actually used, signaling callers that
+ * migrated on write (see `installFromManifest`). */
+export async function readManifestWithFallback(loc) {
+    const root = await readManifestFile(loc.manifestPath);
+    if (root !== null)
+        return { manifest: root, legacyPath: null };
+    if (loc.target.kind !== "repo")
+        return { manifest: null, legacyPath: null };
+    const legacyPath = join(loc.targetDir, LEGACY_MANIFEST_PATH);
+    const legacy = await readManifestFile(legacyPath);
+    if (legacy === null)
+        return { manifest: null, legacyPath: null };
+    return { manifest: legacy, legacyPath };
+}
+export async function writeManifestFile(manifestPath, manifest) {
+    await mkdir(dirname(manifestPath), { recursive: true });
+    // Randomized suffix: two concurrent writers (e.g. install + agent sync) never collide on the same tmp path.
+    const tmp = `${manifestPath}.${randomBytes(6).toString("hex")}.tmp`;
+    await writeFile(tmp, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    try {
+        await rename(tmp, manifestPath);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => { }); // best-effort: don't leave the tmp file behind on a failed rename
+        throw err;
+    }
+}

package/dist/plan.d.ts

@@ -0,0 +1,7 @@
+import type { Bundle, Manifest, ReconcilePlan } from "./types.ts";
+/**
+ * Pure desired-state diff. `onDisk` must cover every path in bundle.files ∪ manifest.files
+ * (null = absent). Paths outside that union are structurally unreachable here — the
+ * never-clobber guarantee starts in this signature.
+ */
+export declare function planReconcile(bundle: Bundle, manifest: Manifest, onDisk: Record<string, string | null>): ReconcilePlan;

package/dist/plan.js

@@ -0,0 +1,34 @@
+import { sha256 } from "./hash.js";
+/**
+ * Pure desired-state diff. `onDisk` must cover every path in bundle.files ∪ manifest.files
+ * (null = absent). Paths outside that union are structurally unreachable here — the
+ * never-clobber guarantee starts in this signature.
+ */
+export function planReconcile(bundle, manifest, onDisk) {
+    const writes = [];
+    const unchanged = [];
+    const drifted = [];
+    for (const [path, desired] of Object.entries(bundle.files)) {
+        const current = onDisk[path] ?? null;
+        if (current === desired)
+            unchanged.push(path);
+        else
+            writes.push(path);
+    }
+    const deletes = [];
+    for (const path of Object.keys(manifest.files)) {
+        if (!(path in bundle.files) && (onDisk[path] ?? null) !== null)
+            deletes.push(path);
+    }
+    for (const [path, managedHash] of Object.entries(manifest.files)) {
+        const current = onDisk[path] ?? null;
+        if (current !== null && sha256(current) !== managedHash)
+            drifted.push(path);
+    }
+    return {
+        writes: writes.sort(),
+        deletes: deletes.sort(),
+        drifted: drifted.sort(),
+        unchanged: unchanged.sort(),
+    };
+}

package/dist/resolve-packs.d.ts

@@ -0,0 +1,44 @@
+import { type HarnessManifest, type Resolution, type WorkflowPack } from "@baselane/packs";
+export interface ResolvedManifestPacks {
+    packs: Record<string, WorkflowPack>;
+    resolutions: Record<string, Resolution>;
+    notes: string[];
+}
+/** CLI default registry, overridden by `manifest.registry`, then a caller-supplied `registryBase`
+ * (the CLI reads `BASELANE_REGISTRY` and passes it through — env access stays out of this
+ * package, same as how `GITHUB_TOKEN` flows in as `opts.token`). Spec: RETURN DECISION 4. */
+export declare const DEFAULT_REGISTRY = "https://registry.baselane.sh";
+export declare function registryBaseFor(manifest: HarnessManifest, fallback?: string): string;
+export interface RegistryVersionEntry {
+    version: string;
+    source: {
+        name: string;
+        ref: string;
+        sha: string;
+    };
+    packId: string;
+    publishedAt: string;
+}
+/** GET {registryBase}/registry/v1/packs/{name} — every entry validated against the registry's
+ * own publish-time shape (semver version, `github:` source, 40-hex lowercase sha); entries that
+ * fail are dropped (never written to a committed manifest pin), with a notice so a silently
+ * degraded registry response isn't invisible. The kept entries are sorted semver-desc locally —
+ * "latest" must never trust server-supplied order. */
+export declare function fetchRegistryVersions(name: string, registryBase: string, ctx?: {
+    fetchImpl?: typeof fetch;
+    onNotice?: (m: string) => void;
+}): Promise<RegistryVersionEntry[]>;
+export declare function encodeSkillPin(ref: string, skill: string): string;
+/** Exported for display code (e.g. formatting an install/update report) — the raw pin string
+ * contains a control character and must never be printed verbatim. */
+export declare function decodeSkillPin(pin: string): {
+    ref: string;
+    onlySkill: string | undefined;
+};
+export declare function resolveManifestPacks(manifest: HarnessManifest, opts?: {
+    token?: string;
+    fetchImpl?: typeof fetch;
+    onNotice?: (m: string) => void;
+    inlinePacks?: Record<string, WorkflowPack>;
+    registryBase?: string;
+}): Promise<ResolvedManifestPacks>;

package/dist/resolve-packs.js

@@ -0,0 +1,146 @@
+import { packFromFileset, validatePack } from "@baselane/packs";
+import { isGitSourceName, parseGitSourceName, resolveGitSource } from "@baselane/distribute";
+/** CLI default registry, overridden by `manifest.registry`, then a caller-supplied `registryBase`
+ * (the CLI reads `BASELANE_REGISTRY` and passes it through — env access stays out of this
+ * package, same as how `GITHUB_TOKEN` flows in as `opts.token`). Spec: RETURN DECISION 4. */
+export const DEFAULT_REGISTRY = "https://registry.baselane.sh";
+export function registryBaseFor(manifest, fallback) {
+    return manifest.registry ?? fallback ?? DEFAULT_REGISTRY;
+}
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+const SOURCE_NAME_RE = /^github:[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+/** 3-part numeric semver compare, descending ("1.10.0" sorts before "1.2.0"). Mirrors
+ * apps/portal/src/compliance.ts's compareVersions — inlined because packages can't import
+ * from apps/portal. ALL client-side "latest" resolution must go through this, never trust
+ * the order the registry response happened to arrive in. */
+function compareVersionsDesc(a, b) {
+    const part = (v, i) => Number.parseInt(v.split(".")[i] ?? "0", 10);
+    for (let i = 0; i < 3; i++) {
+        const d = part(b, i) - part(a, i);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** A registry is an untrusted network response, not a trusted local store — a malicious or
+ * buggy server could otherwise write a non-semver version, a non-github: source, or a
+ * malformed sha straight into a committed harness.json pin. Reject anything that doesn't
+ * match the exact shape the portal's own RegistryIndexRec validator enforces at publish time. */
+function isValidRegistryVersionEntry(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const r = v;
+    if (typeof r.version !== "string" || !VERSION_RE.test(r.version))
+        return false;
+    if (typeof r.packId !== "string" || r.packId.length === 0)
+        return false;
+    if (typeof r.publishedAt !== "string")
+        return false;
+    const source = r.source;
+    if (source === null || typeof source !== "object")
+        return false;
+    if (typeof source.name !== "string" || !SOURCE_NAME_RE.test(source.name))
+        return false;
+    if (typeof source.ref !== "string" || source.ref.length === 0)
+        return false;
+    if (typeof source.sha !== "string" || !SHA_RE.test(source.sha))
+        return false;
+    return true;
+}
+/** GET {registryBase}/registry/v1/packs/{name} — every entry validated against the registry's
+ * own publish-time shape (semver version, `github:` source, 40-hex lowercase sha); entries that
+ * fail are dropped (never written to a committed manifest pin), with a notice so a silently
+ * degraded registry response isn't invisible. The kept entries are sorted semver-desc locally —
+ * "latest" must never trust server-supplied order. */
+export async function fetchRegistryVersions(name, registryBase, ctx = {}) {
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${registryBase}/registry/v1/packs/${name}`);
+    }
+    catch (err) {
+        throw new Error(`registry: lookup for "${name}" at ${registryBase} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status === 404)
+        throw new Error(`registry: pack "${name}" not found at ${registryBase}`);
+    if (!res.ok)
+        throw new Error(`registry: lookup for "${name}" at ${registryBase} failed with HTTP ${res.status}`);
+    const body = (await res.json());
+    if (!Array.isArray(body.versions))
+        throw new Error(`registry: malformed response for "${name}" at ${registryBase} (missing "versions")`);
+    const valid = body.versions.filter(isValidRegistryVersionEntry);
+    const dropped = body.versions.length - valid.length;
+    if (dropped > 0) {
+        ctx.onNotice?.(`registry: dropped ${dropped} malformed version entr${dropped === 1 ? "y" : "ies"} for "${name}" ` +
+            `at ${registryBase} (bad version/source/sha shape) — refusing to trust them`);
+    }
+    return valid.sort((a, b) => compareVersionsDesc(a.version, b.version));
+}
+/** The `owner/repo@skill` shorthand (no explicit ref) resolves to a `github:owner/repo` manifest
+ * entry pinned at the repo's default branch — but the single-skill filter it implies has nowhere
+ * else to live (manifest pins are plain ref strings, `Record<string,string>`; touching that shape
+ * ripples through validateManifest/buildManifest/materializeHarness for a one-slice feature).
+ * Instead the filter rides along inside the pin string itself, behind a control-character
+ * separator no real git ref name can contain (git refuses control chars in ref names) — so this
+ * is unambiguous and invisible to any pin that isn't skill-scoped. */
+const SKILL_PIN_SEP = "
";
+export function encodeSkillPin(ref, skill) {
+    return `${ref}${SKILL_PIN_SEP}${skill}`;
+}
+/** Exported for display code (e.g. formatting an install/update report) — the raw pin string
+ * contains a control character and must never be printed verbatim. */
+export function decodeSkillPin(pin) {
+    const at = pin.indexOf(SKILL_PIN_SEP);
+    if (at === -1)
+        return { ref: pin, onlySkill: undefined };
+    return { ref: pin.slice(0, at), onlySkill: pin.slice(at + 1) };
+}
+export async function resolveManifestPacks(manifest, opts = {}) {
+    const packs = {};
+    const resolutions = {};
+    const notes = [];
+    const registryBase = registryBaseFor(manifest, opts.registryBase);
+    for (const [name, pin] of Object.entries(manifest.packs)) {
+        const inline = opts.inlinePacks?.[name];
+        if (inline !== undefined) {
+            packs[name] = validatePack(inline);
+            continue;
+        }
+        if (isGitSourceName(name)) {
+            const { repo } = parseGitSourceName(name);
+            const { ref, onlySkill } = decodeSkillPin(pin);
+            const resolved = await resolveGitSource({ name, ref, token: opts.token, fetchImpl: opts.fetchImpl, onNotice: opts.onNotice });
+            const result = await packFromFileset(resolved.files, { repoName: repo, ref, sha: resolved.sha, onlySkill });
+            packs[name] = result.pack;
+            resolutions[name] = { ref: pin, sha: resolved.sha, packId: result.pack.id };
+            if (result.derived) {
+                notes.push(`derived pack from ${name}@${ref}: id "${result.pack.id}", ${(result.pack.skills ?? []).length} skill(s) (no pack.json found — ingested)`);
+            }
+            continue;
+        }
+        // Registry-scoped: `pin` is an exact version (manifest pins are always exact — RETURN
+        // DECISION 4). Look it up in the index, verify the resolved sha against what the index
+        // recorded at publish time (tamper evidence — a moved tag/branch or a compromised registry
+        // record must fail loudly, never resolve silently to different content), then ingest exactly
+        // like a git install.
+        const versions = await fetchRegistryVersions(name, registryBase, { fetchImpl: opts.fetchImpl, onNotice: opts.onNotice });
+        const match = versions.find((v) => v.version === pin);
+        if (!match) {
+            const available = versions.map((v) => v.version).join(", ") || "(none)";
+            throw new Error(`install: "${name}@${pin}" not found in registry ${registryBase} — available versions: ${available}`);
+        }
+        const resolved = await resolveGitSource({
+            name: match.source.name, ref: match.source.ref, token: opts.token, fetchImpl: opts.fetchImpl, onNotice: opts.onNotice,
+        });
+        if (resolved.sha !== match.source.sha) {
+            throw new Error(`install: "${name}@${pin}" tamper check failed — registry index says ${match.source.name}@${match.source.ref} ` +
+                `resolved to sha ${match.source.sha} at publish time, but it currently resolves to ${resolved.sha}`);
+        }
+        const { repo } = parseGitSourceName(match.source.name);
+        const result = await packFromFileset(resolved.files, { repoName: repo, ref: match.source.ref, sha: resolved.sha });
+        packs[name] = result.pack;
+        resolutions[name] = { ref: pin, sha: resolved.sha, packId: result.pack.id };
+    }
+    return { packs, resolutions, notes };
+}

package/dist/settings-merge.d.ts

@@ -0,0 +1,18 @@
+/** Thrown by mergeBaselaneHooks when existing settings are present but aren't a valid JSON
+ * object — the caller must bail on write rather than merge over an empty stand-in, or the
+ * developer's permissions/model/env/MCP config gets silently erased. */
+export declare class SettingsParseError extends Error {
+}
+/**
+ * Whether an existing `~/.claude/settings.json` has any baselane-managed hook entries
+ * that a merge would need to prune. Lets callers skip merging (and rewriting) settings
+ * files we've never touched — e.g. a developer's hand-written settings with no baselane
+ * hooks in them at all.
+ */
+export declare function hasManagedHooks(existingSettingsJson: string | null): boolean;
+/**
+ * Merge this pack's hooks into a developer's existing `~/.claude/settings.json`.
+ * Every hook we own is tagged with a `BASELANE_MANAGED=1 ` command prefix so a later
+ * merge can find and replace our own prior entries without touching the developer's.
+ */
+export declare function mergeBaselaneHooks(existingSettingsJson: string | null, packSettingsJson: string): string;

package/dist/settings-merge.js

@@ -0,0 +1,69 @@
+const BASELANE_PREFIX = "BASELANE_MANAGED=1 ";
+/** Thrown by mergeBaselaneHooks when existing settings are present but aren't a valid JSON
+ * object — the caller must bail on write rather than merge over an empty stand-in, or the
+ * developer's permissions/model/env/MCP config gets silently erased. */
+export class SettingsParseError extends Error {
+}
+function tryParseSettings(json) {
+    try {
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// Lenient: malformed input reads as "no settings at all". Only safe for read-only checks
+// (e.g. "does this file already have managed hooks to prune?") — never for deciding what to
+// WRITE. mergeBaselaneHooks below parses strictly and throws instead.
+function parseSettings(json) {
+    if (json === null)
+        return {};
+    return tryParseSettings(json) ?? {};
+}
+function isBaselaneManaged(entry) {
+    return entry.hooks.some((h) => h.command.startsWith(BASELANE_PREFIX));
+}
+/**
+ * Whether an existing `~/.claude/settings.json` has any baselane-managed hook entries
+ * that a merge would need to prune. Lets callers skip merging (and rewriting) settings
+ * files we've never touched — e.g. a developer's hand-written settings with no baselane
+ * hooks in them at all.
+ */
+export function hasManagedHooks(existingSettingsJson) {
+    const existing = parseSettings(existingSettingsJson);
+    const existingHooks = existing.hooks ?? {};
+    return Object.values(existingHooks).some((entries) => entries.some(isBaselaneManaged));
+}
+/**
+ * Merge this pack's hooks into a developer's existing `~/.claude/settings.json`.
+ * Every hook we own is tagged with a `BASELANE_MANAGED=1 ` command prefix so a later
+ * merge can find and replace our own prior entries without touching the developer's.
+ */
+export function mergeBaselaneHooks(existingSettingsJson, packSettingsJson) {
+    let existing = {};
+    if (existingSettingsJson !== null) {
+        const parsed = tryParseSettings(existingSettingsJson);
+        if (parsed === null) {
+            throw new SettingsParseError("existing settings.json is not a valid JSON object — refusing to merge over it");
+        }
+        existing = parsed;
+    }
+    const pack = parseSettings(packSettingsJson);
+    const existingHooks = existing.hooks ?? {};
+    const packHooks = pack.hooks ?? {};
+    const events = [...new Set([...Object.keys(existingHooks), ...Object.keys(packHooks)])];
+    const mergedHooks = {};
+    for (const event of events) {
+        const kept = (existingHooks[event] ?? []).filter((entry) => !isBaselaneManaged(entry));
+        const ours = (packHooks[event] ?? []).map((entry) => ({
+            ...entry,
+            hooks: entry.hooks.map((h) => ({ ...h, command: BASELANE_PREFIX + h.command })),
+        }));
+        mergedHooks[event] = [...kept, ...ours];
+    }
+    const merged = { ...existing, hooks: mergedHooks };
+    return JSON.stringify(merged, null, 2) + "\n";
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+/** One onboarding step the portal wants surfaced to this device's developer (bundle version 2). */
+export interface BundleOnboardingStep {
+    packId: string;
+    stepId: string;
+    title: string;
+    description: string;
+    command?: string;
+}
+/** Approved config bundle: target-relative POSIX path → file content. Version 2 adds informational
+ * metadata (the effective pack ids, whole-file collisions, and pending onboarding steps); the
+ * file-map contract is unchanged, so a version-1 bundle is a strict subset. */
+export interface Bundle {
+    version: 1 | 2;
+    files: Record<string, string>;
+    packIds?: string[];
+    collisions?: string[];
+    onboarding?: BundleOnboardingStep[];
+}
+/** What baselane manages in the target dir: path → sha256 of the content we wrote. */
+export interface Manifest {
+    version: 1;
+    files: Record<string, string>;
+}
+/** Result of planning a reconcile — pure data, no side effects. */
+export interface ReconcilePlan {
+    /** Bundle paths whose on-disk content differs (or is absent): will be (over)written. */
+    writes: string[];
+    /** Paths in the manifest but not in the bundle and still on disk: will be removed. */
+    deletes: string[];
+    /** Managed paths whose on-disk content no longer matches the manifest hash (local edits). */
+    drifted: string[];
+    /** Bundle paths already byte-identical on disk. */
+    unchanged: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@baselane/materialize",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Disk-reconcile and install engine (plan/apply/receipt/settings-merge/manifest-io/resolve/install) shared by the baselane CLI and desktop agent.",
+  "main": "./dist/index.js",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammad0omar/baselane.sh.git",
+    "directory": "packages/materialize"
+  },
+  "homepage": "https://baselane.sh",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@baselane/packs": "0.1.0",
+    "@baselane/distribute": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "types": "./dist/index.d.ts"
+}