@codyswann/lisa 4.60.11 → 4.61.0

package/all/copy-overwrite/scripts/lib/process-tree-runner.mjs

@@ -3,14 +3,18 @@
 // Do not edit directly — durable changes belong upstream in Lisa.
 
 /**
- * Run one shell command in its own process group and reap the whole group.
+ * Run one shell command in a process boundary and reap every descendant.
  *
  * Node's synchronous timeout signals only the direct child. A gate command is
  * a tree (shell, package manager, test workers), so killing only the shell
  * leaves descendants running against scratch state the caller then removes.
  * This small asynchronous supervisor is invoked through a synchronous parent:
  * it owns the process-group id, applies the deadline, terminates the group, and
- * only then lets the parent continue.
+ * only then lets the parent continue. On Windows, the common PowerShell helper
+ * owns a native Job Object because a shell PID cannot identify descendants
+ * after the shell exits. Windows 10 / Server 2016 or newer and the installed
+ * Windows PowerShell execution policy must permit that helper; startup failure
+ * rejects the command without an uncontained fallback.
  *
  * ## Interrupting a run
  *
@@ -31,6 +35,7 @@
 import { spawn, spawnSync } from "node:child_process";
 
 import { invokedAsScript } from "./invoked-as-script.mjs";
+import { startWindowsProcessJob } from "./windows-process-job.mjs";
 
 const KILL_GRACE_MS = 750;
 const REAP_POLL_MS = 25;
@@ -407,7 +412,7 @@ export async function reapTree(pid, controls = DEFAULT_REAP_CONTROLS) {
  * lands on a recycled pid.
  * @param {string} command Shell source to supervise.
  * @param {number} timeoutMs Deadline for the whole tree.
- * @param {typeof reapTree} [reap] Injectable group reaper.
+ * @param {typeof reapTree} [reap] Injectable POSIX group reaper. Windows retains its native job owner.
  * @param {object} [options] Interrupt-watch seams, injectable for tests.
  * @param {readonly number[]} [options.watchPids] Pids whose death ends this run.
  * @param {typeof interruptionReason} [options.detect] Interrupt predicate.
@@ -425,14 +430,7 @@ export function supervise(command, timeoutMs, reap = reapTree, options = {}) {
     launchParentPid = process.ppid,
   } = options;
   return new Promise((resolve, reject) => {
-    const shell =
-      process.platform === "win32"
-        ? process.env.ComSpec || "cmd.exe"
-        : "/bin/sh";
-    const shellArgs =
-      process.platform === "win32"
-        ? ["/d", "/s", "/c", command]
-        : ["-c", command];
+    let windowsJob;
     let pendingSignal;
     let dispatchSignal = signal => {
       pendingSignal ??= signal;
@@ -455,7 +453,11 @@ export function supervise(command, timeoutMs, reap = reapTree, options = {}) {
 
     const child = (() => {
       try {
-        return spawn(shell, shellArgs, {
+        if (process.platform === "win32") {
+          windowsJob = startWindowsProcessJob(command);
+          return windowsJob.child;
+        }
+        return spawn("/bin/sh", ["-c", command], {
           detached: true,
           env: process.env,
           stdio: "inherit",
@@ -501,7 +503,7 @@ export function supervise(command, timeoutMs, reap = reapTree, options = {}) {
     // shell's close handler is reaping must join that operation instead of
     // starting a second kill sequence or taking the default signal action.
     const reapOnce = () => {
-      reapPromise ??= reap(pid);
+      reapPromise ??= windowsJob ? windowsJob.reap() : reap(pid);
       return reapPromise;
     };
     const finish = async (code, signal) => {

package/all/copy-overwrite/scripts/lib/windows-process-job.cs

@@ -0,0 +1,249 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+// Windows 10 / Server 2016 or newer: create the shell inside its Job Object.
+using System;
+using System.ComponentModel;
+using System.Diagnostics;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+
+/// <summary>Runs a shell inside a retained job and confirms its descendants have exited.</summary>
+public static class LisaWindowsProcessJob
+{
+    [StructLayout(LayoutKind.Sequential)]
+    struct BasicLimits
+    {
+        public long ProcessTime, JobTime;
+        public uint Flags;
+        public UIntPtr MinimumWorkingSet, MaximumWorkingSet;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint Priority, SchedulingClass;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct ExtendedLimits
+    {
+        public BasicLimits Basic;
+        public ulong ReadOperations, WriteOperations, OtherOperations;
+        public ulong ReadBytes, WriteBytes, OtherBytes;
+        public UIntPtr ProcessMemory, JobMemory, PeakProcessMemory, PeakJobMemory;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct Accounting
+    {
+        public long UserTime, KernelTime, PeriodUserTime, PeriodKernelTime;
+        public uint PageFaults, TotalProcesses, ActiveProcesses, TerminatedProcesses;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct StartupInfo
+    {
+        public uint Size;
+        public IntPtr Reserved, Desktop, Title;
+        public uint X, Y, Width, Height, XCount, YCount, Fill, Flags;
+        public ushort ShowWindow, ReservedLength;
+        public IntPtr ReservedData, Input, Output, Error;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct StartupInfoEx
+    {
+        public StartupInfo Startup;
+        public IntPtr Attributes;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct ProcessInformation
+    {
+        public IntPtr Process, Thread;
+        public uint ProcessId, ThreadId;
+    }
+
+    /// <summary>Creates the helper-owned job handle, which is never inherited by the shell.</summary>
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern IntPtr CreateJobObjectW(IntPtr attributes, string name);
+    /// <summary>Applies the job limits used to kill members when its final handle closes.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool SetInformationJobObject(IntPtr job, int kind, ref ExtendedLimits value, uint size);
+    /// <summary>Reads job accounting so cleanup can confirm zero active processes.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool QueryInformationJobObject(IntPtr job, int kind, out Accounting value, uint size, IntPtr returned);
+    /// <summary>Requests termination of every process retained in the job.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool TerminateJobObject(IntPtr job, uint code);
+    /// <summary>Measures or initializes storage for the two process-creation attributes.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool InitializeProcThreadAttributeList(IntPtr list, int count, uint flags, ref IntPtr size);
+    /// <summary>Adds the job binding or restricted inherited-handle list before process creation.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool UpdateProcThreadAttribute(IntPtr list, uint flags, IntPtr attribute, IntPtr value, IntPtr size, IntPtr previous, IntPtr returned);
+    /// <summary>Releases initialized attribute-list contents before their backing memory is freed.</summary>
+    [DllImport("kernel32.dll")]
+    static extern void DeleteProcThreadAttributeList(IntPtr list);
+    /// <summary>Creates the shell with job membership and explicit standard handles already assigned.</summary>
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern bool CreateProcessW(string application, StringBuilder command, IntPtr processAttributes, IntPtr threadAttributes, bool inheritHandles, uint flags, IntPtr environment, string directory, ref StartupInfoEx startup, out ProcessInformation process);
+    /// <summary>Polls the shell handle while allowing stop-file and owner-exit checks.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+    /// <summary>Reads the shell exit code after its process handle signals completion.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool GetExitCodeProcess(IntPtr process, out uint code);
+    /// <summary>Releases an owned native handle without closing borrowed caller handles.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool CloseHandle(IntPtr handle);
+    /// <summary>Supplies the current-process pseudo handle for standard-handle duplication.</summary>
+    [DllImport("kernel32.dll")]
+    static extern IntPtr GetCurrentProcess();
+    /// <summary>Reads a borrowed standard handle, which may be absent in a service process.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern IntPtr GetStdHandle(int kind);
+    /// <summary>Opens a temporary NUL device handle when a standard stream is absent.</summary>
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    static extern IntPtr CreateFileW(string name, uint access, uint share, IntPtr attributes, uint creation, uint flags, IntPtr template);
+    /// <summary>Creates an inheritable duplicate while retaining ownership of the original handle.</summary>
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool DuplicateHandle(IntPtr sourceProcess, IntPtr source, IntPtr targetProcess, out IntPtr target, uint access, bool inherit, uint options);
+
+    /// <summary>Throws with the captured native error when an operation reports failure.</summary>
+    static void Check(bool ok, string operation)
+    {
+        if (!ok) throw new Win32Exception(Marshal.GetLastWin32Error(), operation);
+    }
+
+    /// <summary>Returns an owned inheritable standard handle, substituting NUL only when absent.</summary>
+    /// <param name="kind">The native standard-input, output, or error handle identifier.</param>
+    /// <returns>A duplicate that Run must close after the contained command finishes.</returns>
+    static IntPtr StandardHandle(int kind)
+    {
+        IntPtr source = GetStdHandle(kind);
+        bool absent = source == IntPtr.Zero || source == new IntPtr(-1);
+        if (absent)
+        {
+            // Services may have no standard handles. Supply EOF/discard devices
+            // while preserving any real redirected handles supplied by callers.
+            source = CreateFileW("NUL", kind == -10 ? 0x80000000u : 0x40000000u, 3, IntPtr.Zero, 3, 0, IntPtr.Zero);
+            Check(source != new IntPtr(-1), "Open absent gate standard handle");
+        }
+        try
+        {
+            IntPtr result;
+            Check(DuplicateHandle(GetCurrentProcess(), source, GetCurrentProcess(), out result, 0, true, 2), "Duplicate gate standard handle");
+            return result;
+        }
+        finally
+        {
+            if (absent) CloseHandle(source);
+        }
+    }
+
+    /// <summary>Terminates job members and waits up to five seconds for empty membership.</summary>
+    /// <param name="job">The retained job handle; this method does not close it.</param>
+    static void TerminateAndWait(IntPtr job)
+    {
+        Check(TerminateJobObject(job, 255), "Terminate gate job");
+        Stopwatch deadline = Stopwatch.StartNew();
+        for (;;)
+        {
+            Accounting state;
+            Check(QueryInformationJobObject(job, 1, out state, (uint)Marshal.SizeOf(typeof(Accounting)), IntPtr.Zero), "Read gate job membership");
+            if (state.ActiveProcesses == 0) return;
+            if (deadline.ElapsedMilliseconds >= 5000) throw new TimeoutException("Gate job still has processes after termination");
+            Thread.Sleep(25);
+        }
+    }
+
+    /// <summary>Runs a contained command and reaps its descendants before returning.</summary>
+    /// <remarks>
+    /// The helper owns the job outside its membership. A helper crash closes
+    /// its non-inherited job handle and kills the job as a backstop.
+    /// </remarks>
+    /// <param name="command">The shell command, forwarded without rewriting its arguments.</param>
+    /// <param name="controlDirectory">The caller-owned directory containing the stop marker.</param>
+    /// <param name="parent">The retained owner process whose exit requests cancellation.</param>
+    /// <returns>The shell exit code, or 255 when interrupted before normal completion.</returns>
+    public static int Run(string command, string controlDirectory, Process parent)
+    {
+        IntPtr job = IntPtr.Zero, attributes = IntPtr.Zero;
+        IntPtr jobValue = IntPtr.Zero, handleValues = IntPtr.Zero;
+        bool attributesInitialized = false;
+        IntPtr[] standard = new IntPtr[3];
+        ProcessInformation child = new ProcessInformation();
+        uint result = 255;
+        try
+        {
+            job = CreateJobObjectW(IntPtr.Zero, null);
+            Check(job != IntPtr.Zero, "Create gate job");
+            ExtendedLimits limits = new ExtendedLimits();
+            limits.Basic.Flags = 0x2000; // JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE.
+            Check(SetInformationJobObject(job, 9, ref limits, (uint)Marshal.SizeOf(typeof(ExtendedLimits))), "Set gate job lifetime");
+
+            IntPtr size = IntPtr.Zero;
+            InitializeProcThreadAttributeList(IntPtr.Zero, 2, 0, ref size);
+            Check(size != IntPtr.Zero, "Measure gate process attributes");
+            attributes = Marshal.AllocHGlobal(size);
+            Check(InitializeProcThreadAttributeList(attributes, 2, 0, ref size), "Initialize gate process attributes");
+            attributesInitialized = true;
+            jobValue = Marshal.AllocHGlobal(IntPtr.Size);
+            Marshal.WriteIntPtr(jobValue, job);
+            // PROC_THREAD_ATTRIBUTE_JOB_LIST binds before the first instruction;
+            // suspended-create followed by assignment has an orphaning window.
+            Check(UpdateProcThreadAttribute(attributes, 0, new IntPtr(0x2000D), jobValue, new IntPtr(IntPtr.Size), IntPtr.Zero, IntPtr.Zero), "Bind gate to job at creation");
+
+            handleValues = Marshal.AllocHGlobal(3 * IntPtr.Size);
+            for (int i = 0; i < 3; ++i)
+            {
+                standard[i] = StandardHandle(-10 - i);
+                Marshal.WriteIntPtr(handleValues, i * IntPtr.Size, standard[i]);
+            }
+            Check(UpdateProcThreadAttribute(attributes, 0, new IntPtr(0x20002), handleValues, new IntPtr(3 * IntPtr.Size), IntPtr.Zero, IntPtr.Zero), "Limit inherited gate handles");
+            StartupInfoEx startup = new StartupInfoEx();
+            startup.Startup.Size = (uint)Marshal.SizeOf(typeof(StartupInfoEx));
+            startup.Startup.Flags = 0x100; // STARTF_USESTDHANDLES.
+            startup.Startup.Input = standard[0];
+            startup.Startup.Output = standard[1];
+            startup.Startup.Error = standard[2];
+            startup.Attributes = attributes;
+            string shell = Environment.GetEnvironmentVariable("ComSpec") ?? Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "cmd.exe");
+            StringBuilder line = new StringBuilder("\"" + shell + "\" /d /s /c \"" + command + "\"");
+            // Never launch a command after a stop or owner exit during startup.
+            if (File.Exists(Path.Combine(controlDirectory, "stop")) || parent.WaitForExit(0)) return 255;
+            Check(CreateProcessW(shell, line, IntPtr.Zero, IntPtr.Zero, true, 0x80000, IntPtr.Zero, Environment.CurrentDirectory, ref startup, out child), "Create contained gate command");
+            for (;;)
+            {
+                uint wait = WaitForSingleObject(child.Process, 25);
+                if (wait == 0)
+                {
+                    Check(GetExitCodeProcess(child.Process, out result), "Read gate command exit");
+                    break;
+                }
+                Check(wait == 258, "Wait for gate command");
+                if (File.Exists(Path.Combine(controlDirectory, "stop")) || parent.WaitForExit(0)) break;
+            }
+        }
+        finally
+        {
+            // Release our process handles before checking membership accounting.
+            if (child.Thread != IntPtr.Zero) CloseHandle(child.Thread);
+            if (child.Process != IntPtr.Zero) CloseHandle(child.Process);
+            try
+            {
+                if (job != IntPtr.Zero) TerminateAndWait(job);
+            }
+            finally
+            {
+                if (job != IntPtr.Zero) CloseHandle(job);
+                foreach (IntPtr handle in standard) if (handle != IntPtr.Zero) CloseHandle(handle);
+                if (attributesInitialized) DeleteProcThreadAttributeList(attributes);
+                if (attributes != IntPtr.Zero) Marshal.FreeHGlobal(attributes);
+                if (jobValue != IntPtr.Zero) Marshal.FreeHGlobal(jobValue);
+                if (handleValues != IntPtr.Zero) Marshal.FreeHGlobal(handleValues);
+            }
+        }
+        return unchecked((int)result);
+    }
+}

package/all/copy-overwrite/scripts/lib/windows-process-job.mjs

@@ -0,0 +1,119 @@
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+// The Windows-only helper owns a Job Object until all of its processes exit.
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { env } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const CLEANUP_TIMEOUT_MS = 30000;
+
+/**
+ * Launch the Windows shell in a native job and return its cleanup operation.
+ * @param {string} command Shell source to run.
+ * @returns {{child: import("node:child_process").ChildProcess, reap: () => Promise<void>}} Native process boundary.
+ */
+export function startWindowsProcessJob(command) {
+  const directory = mkdtempSync(path.join(tmpdir(), "lisa-windows-job-"));
+  const powershell = path.join(
+    env.SystemRoot || "C:\\Windows",
+    "System32",
+    "WindowsPowerShell",
+    "v1.0",
+    "powershell.exe"
+  );
+  const script = fileURLToPath(
+    new URL("./windows-process-job.ps1", import.meta.url)
+  );
+  let child;
+  try {
+    child = spawn(
+      powershell,
+      ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", script],
+      {
+        // The native job supplies isolation. Keep the helper attached so
+        // Windows PowerShell retains the caller's standard handles.
+        stdio: "inherit",
+        env: {
+          ...env,
+          TEMP: directory,
+          TMP: directory,
+          LISA_WINDOWS_PROCESS_JOB: JSON.stringify({
+            command,
+            directory,
+            parentPid: process.pid,
+            cwd: process.cwd(),
+            originalTemp: env.TEMP ?? null,
+            originalTmp: env.TMP ?? null,
+          }),
+        },
+      }
+    );
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  let closed = false;
+  const completion = new Promise(resolve => {
+    child.once("close", () => {
+      closed = true;
+      resolve();
+    });
+    child.once("error", () => {
+      if (child.pid === undefined)
+        rmSync(directory, { recursive: true, force: true });
+    });
+  });
+  const reap = async () => {
+    let timer;
+    try {
+      if (!closed) writeFileSync(path.join(directory, "stop"), "stop");
+      await Promise.race([
+        completion,
+        new Promise((_, reject) => {
+          timer = setTimeout(() => {
+            // Killing the owner closes its job handle as a last resort, but
+            // cannot supply a completed wait: reject instead of claiming reap.
+            child.kill("SIGKILL");
+            reject(
+              new Error("Windows gate helper did not complete its cleanup wait")
+            );
+          }, CLEANUP_TIMEOUT_MS);
+        }),
+      ]);
+      if (readFileSync(path.join(directory, "reaped"), "utf8") !== "reaped") {
+        throw new Error("Windows gate helper did not confirm an empty job");
+      }
+    } catch (error) {
+      // A failed stop-file write must still close the job owner. Its native
+      // KILL_ON_JOB_CLOSE limit stops contained processes; the finally block
+      // waits for helper close before removing scratch. Keep this a failure:
+      // forced termination cannot provide the normal empty-job receipt.
+      if (!closed && !child.killed) child.kill("SIGKILL");
+      throw new Error(
+        `Windows gate cleanup was not verified (helper exit ${child.exitCode ?? child.signalCode ?? "pending"}): ${error.message}`
+      );
+    } finally {
+      clearTimeout(timer);
+      if (!closed) {
+        // Give a killed helper time to close before a CLI rejection exits Node.
+        // Still bound failure when the OS cannot stop the helper promptly.
+        await Promise.race([
+          completion,
+          new Promise(resolve => {
+            timer = setTimeout(resolve, 1000);
+          }),
+        ]);
+        clearTimeout(timer);
+      }
+      if (closed) rmSync(directory, { recursive: true, force: true });
+      else
+        child.once("close", () =>
+          rmSync(directory, { recursive: true, force: true })
+        );
+    }
+  };
+  return { child, reap };
+}

package/all/copy-overwrite/scripts/lib/windows-process-job.ps1

@@ -0,0 +1,25 @@
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+# Use the installed Windows PowerShell policy; never override execution policy.
+$ErrorActionPreference = 'Stop'
+$parent = $null
+try {
+    $config = $env:LISA_WINDOWS_PROCESS_JOB | ConvertFrom-Json
+    Remove-Item Env:LISA_WINDOWS_PROCESS_JOB
+    $parent = [Diagnostics.Process]::GetProcessById([int]$config.parentPid)
+    $null = $parent.Handle
+    Add-Type -Path (Join-Path $PSScriptRoot 'windows-process-job.cs')
+    # Compiler scratch belongs to this helper; the gate retains its original env.
+    [Environment]::SetEnvironmentVariable('TEMP', $config.originalTemp)
+    [Environment]::SetEnvironmentVariable('TMP', $config.originalTmp)
+    [Environment]::CurrentDirectory = $config.cwd
+    $code = [LisaWindowsProcessJob]::Run($config.command, $config.directory, $parent)
+    # Only a completed native membership wait may authorize a successful reap.
+    [IO.File]::WriteAllText((Join-Path $config.directory 'reaped'), 'reaped')
+    exit $code
+} catch {
+    [Console]::Error.WriteLine('Windows gate containment failed: ' + $_.Exception.Message)
+    exit 1
+} finally {
+    if ($null -ne $parent) { $parent.Dispose() }
+}

package/dist/cli/starter-sync-content.d.ts

@@ -0,0 +1,25 @@
+import type { TemplateCandidate } from "../health/template-inspection.js";
+import type { StarterChange } from "./starter-sync-source.js";
+/**
+ * Resolve canonical markers; markerless copy-contents uses whole-file ownership.
+ * @param candidates - Applicable copy-contents template sources.
+ * @returns Distinct governed opening markers.
+ */
+export declare function starterBlockMarkers(candidates: readonly TemplateCandidate[]): Promise<readonly string[]>;
+/**
+ * Apply only the blocks governed by the existing canonical template sources.
+ * @param change - Exact before/after starter file.
+ * @param current - Existing consumer bytes.
+ * @param markers - Canonical opening markers for this path.
+ * @returns Updated bytes, preserving all consumer content outside those blocks.
+ */
+export declare function mergeStarterBlocks(change: StarterChange, current: Buffer | undefined, markers: readonly string[]): Promise<Buffer>;
+/**
+ * Reuse Lisa's JSON strategies for paths governed by JSON merge semantics.
+ * @param change - Pinned starter JSON file.
+ * @param current - Existing consumer bytes.
+ * @param candidates - Applicable JSON strategies in canonical order.
+ * @returns Merged bytes; source removal preserves the consumer's JSON document.
+ */
+export declare function mergeStarterJson(change: StarterChange, current: Buffer | undefined, candidates: readonly TemplateCandidate[]): Buffer | undefined;
+//# sourceMappingURL=starter-sync-content.d.ts.map

package/dist/cli/starter-sync-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-sync-content.d.ts","sourceRoot":"","sources":["../../src/cli/starter-sync-content.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAQ1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAyD9D;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GACvC,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAW5B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,UAAU,EAAE,SAAS,iBAAiB,EAAE,GACvC,MAAM,GAAG,SAAS,CAiBpB"}

package/dist/cli/starter-sync-content.js

@@ -0,0 +1,106 @@
+import { readFile } from "node:fs/promises";
+import { findCopyContentsBlock, mergeCopyContents, } from "../strategies/copy-contents.js";
+import { mergeTemplateJson } from "../strategies/merge.js";
+import { TaggedMergeStrategy } from "../strategies/tagged-merge.js";
+import { isJsonObject } from "../sync/json-path.js";
+const BEGIN = "# BEGIN: AI GUARDRAILS";
+const END = "# END: AI GUARDRAILS";
+/**
+ * Decode managed text without silently replacing invalid bytes.
+ * @param bytes - File payload, if the path exists.
+ * @returns Strict UTF-8 content.
+ */
+function text(bytes) {
+    return bytes === undefined
+        ? ""
+        : new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/**
+ * Extract one complete marker pair without importing outside starter content.
+ * @param content - Flat starter or consumer file.
+ * @param begin - Canonical Lisa template's opening marker.
+ * @returns Normalized managed block, or undefined when absent.
+ */
+function block(content, begin) {
+    const end = END + begin.slice(BEGIN.length);
+    const lines = content.split(/\r?\n/u);
+    const starts = lines.flatMap((line, index) => line === begin ? [index] : []);
+    const ends = lines.flatMap((line, index) => (line === end ? [index] : []));
+    if (starts.length === 0 && ends.length === 0)
+        return undefined;
+    if (starts.length !== 1 || ends.length !== 1 || starts[0] >= ends[0]) {
+        throw new Error("Incomplete or ambiguous starter managed block");
+    }
+    return lines.slice(starts[0], ends[0] + 1).join("\n");
+}
+/**
+ * Replace or remove a verified managed block while retaining outside bytes.
+ * @param current - Consumer content.
+ * @param begin - Canonical opening marker.
+ * @param replacement - New block, or undefined for removal.
+ * @returns Updated content.
+ */
+function replaceBlock(current, begin, replacement) {
+    if (replacement !== undefined)
+        return mergeCopyContents(`${replacement}\n`, current);
+    const end = END + begin.slice(BEGIN.length);
+    const offsets = findCopyContentsBlock(current, begin, end);
+    return offsets === undefined
+        ? current
+        : current.slice(0, offsets.start) + current.slice(offsets.end);
+}
+/**
+ * Resolve canonical markers; markerless copy-contents uses whole-file ownership.
+ * @param candidates - Applicable copy-contents template sources.
+ * @returns Distinct governed opening markers.
+ */
+export async function starterBlockMarkers(candidates) {
+    const canonical = await Promise.all(candidates.map(candidate => readFile(candidate.source, "utf8")));
+    return [
+        ...new Set(canonical.flatMap(source => source.split(/\r?\n/u).filter(line => line.startsWith(BEGIN)))),
+    ];
+}
+/**
+ * Apply only the blocks governed by the existing canonical template sources.
+ * @param change - Exact before/after starter file.
+ * @param current - Existing consumer bytes.
+ * @param markers - Canonical opening markers for this path.
+ * @returns Updated bytes, preserving all consumer content outside those blocks.
+ */
+export async function mergeStarterBlocks(change, current, markers) {
+    const before = text(change.before?.bytes);
+    const after = text(change.after?.bytes);
+    const merged = markers.reduce((content, begin) => {
+        const previous = block(before, begin);
+        const next = block(after, begin);
+        const existing = block(content, begin);
+        if (existing === next || previous === next)
+            return content;
+        if (existing !== undefined && existing !== previous)
+            throw new Error(`Starter managed block conflicts with local changes: ${change.path}`);
+        return replaceBlock(content, begin, next);
+    }, text(current));
+    return Buffer.from(merged);
+}
+/**
+ * Reuse Lisa's JSON strategies for paths governed by JSON merge semantics.
+ * @param change - Pinned starter JSON file.
+ * @param current - Existing consumer bytes.
+ * @param candidates - Applicable JSON strategies in canonical order.
+ * @returns Merged bytes; source removal preserves the consumer's JSON document.
+ */
+export function mergeStarterJson(change, current, candidates) {
+    if (change.after === undefined)
+        return current;
+    const source = JSON.parse(text(change.after.bytes));
+    const destination = JSON.parse(current === undefined ? "{}" : text(current));
+    if (!isJsonObject(source) || !isJsonObject(destination))
+        throw new Error(`Starter JSON merge requires objects: ${change.path}`);
+    const merged = candidates.reduce((result, candidate) => candidate.strategy === "tagged-merge"
+        ? new TaggedMergeStrategy().mergeJson(source, result)
+        : mergeTemplateJson(source, result), destination);
+    if (JSON.stringify(merged) === JSON.stringify(destination))
+        return current;
+    return Buffer.from(`${JSON.stringify(merged, null, 2)}\n`);
+}
+//# sourceMappingURL=starter-sync-content.js.map

package/dist/cli/starter-sync-content.js.map

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

package/dist/cli/starter-sync-source.d.ts

@@ -0,0 +1,33 @@
+import type { StarterTemplate } from "../core/project-config-starter.js";
+import { type CaptureCommand } from "./starter-provenance.js";
+/** Exact regular-file or link bytes at one immutable starter revision. */
+export interface StarterFile {
+    readonly bytes: Buffer;
+    readonly mode: string;
+}
+/** A path changed between the recorded baseline and the pinned tracked head. */
+export interface StarterChange {
+    readonly path: string;
+    readonly before?: StarterFile;
+    readonly after?: StarterFile;
+}
+/** A complete, read-only diff suitable for one independently tracked starter. */
+export interface StarterChanges {
+    readonly sha: string;
+    readonly changes: readonly StarterChange[];
+}
+/**
+ * Keep Git paths relative without rejecting colon-scoped agent commands.
+ * @param value - Repository path or configured scope.
+ * @returns Validated path, with a scope's trailing slash removed.
+ */
+export declare function starterRelativePath(value: string): string;
+/**
+ * Diff the actual recorded tree against one pinned head, never a merge base.
+ * @param template - Independently tracked starter and optional path scopes.
+ * @param capture - Bounded read-only GitHub metadata/content runner.
+ * @param accepts - Applicable ownership filter, applied before reading contents.
+ * @returns Complete scoped changes and the exact revision they describe.
+ */
+export declare function readStarterChanges(template: StarterTemplate, capture?: CaptureCommand, accepts?: (name: string) => boolean): Promise<StarterChanges>;
+//# sourceMappingURL=starter-sync-source.d.ts.map

package/dist/cli/starter-sync-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter-sync-source.d.ts","sourceRoot":"","sources":["../../src/cli/starter-sync-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AAEjC,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAoBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWzD;AAyFD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,cAA+B,EACxC,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAoB,GAC9C,OAAO,CAAC,cAAc,CAAC,CA0CzB"}