@launchfile/macos-dev 0.2.0 → 0.4.0

package/dist/provider.js

@@ -6,7 +6,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { readLaunch } from "@launchfile/sdk";
+import { readLaunch, resolveSourcePrepareCommand, resolveSourceRunCommand, selectionClosure, unsuppliedRequiredEnv, } from "@launchfile/sdk";
 import { checkPrereqs } from "./prereqs.js";
 import { loadState, initState, saveState, ensureDirs } from "./state.js";
 import { buildResolverContext, computeAppProperties, resolveComponentEnv, generateSecrets, resolveGenerators, writeEnvFile, } from "./env-writer.js";
@@ -14,9 +14,102 @@ import { getProvisioner } from "./resources/index.js";
 import { allocatePorts } from "./port-allocator.js";
 import { getRuntimeInstaller } from "./runtimes/index.js";
 import { detectPackageManager } from "./lockfile-detect.js";
-import { provisionStorage } from "./storage.js";
+import { provisionStorage, storagePaths } from "./storage.js";
 import { ProcessManager } from "./process-manager.js";
-import { shell } from "./shell.js";
+import { stopRecordedProcesses } from "./process-stopper.js";
+import { shellScript } from "./shell.js";
+import { parseDuration } from "./bootstrap.js";
+/**
+ * This provider runs apps from source. A component is source-runnable when
+ * {@link resolveSourceRunCommand} (D-38) resolves a command — declares `dev`,
+ * or a `start` with no `image`. An `image` without a `dev` override stays
+ * artifact-mode, which this source-only provider can't launch.
+ */
+export function isSourceRunnable(component) {
+    return resolveSourceRunCommand(component) !== undefined;
+}
+/**
+ * Parse a declared timeout, adding the stage/component label to the error.
+ * An unparseable duration is surfaced — it fails the stage that declared it
+ * (PROVIDERS.md §10.10) — never silently replaced with a default. Undefined
+ * passes through so callers keep their own default budgets.
+ */
+function declaredTimeout(timeout, label) {
+    if (timeout === undefined)
+        return undefined;
+    try {
+        return parseDuration(timeout);
+    }
+    catch (err) {
+        throw new Error(`${label}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Components this provider must refuse, mapped to the capabilities it cannot
+ * grant (D-44, PROVIDERS.md §11). Both spellings fold together so the `host:`
+ * entry form and the legacy top-level block produce the same outcome.
+ *
+ * A refusal must remove the component from the run, not merely report it —
+ * this provider grants no host capabilities, so anything listed here cannot
+ * be installed, wired, registered, or started.
+ */
+export function refusedHostCapabilities(launch) {
+    const refused = new Map();
+    for (const [name, c] of Object.entries(launch.components)) {
+        const caps = [];
+        for (const req of c.requires ?? []) {
+            for (const [capability, value] of Object.entries(req.host ?? {})) {
+                caps.push(`${capability}=${String(value)}`);
+            }
+        }
+        if (c.host?.docker === "required")
+            caps.push("container_runtime=docker (host.docker)");
+        if (c.host?.network === "host")
+            caps.push("network=host (host.network)");
+        if (c.host?.privileged)
+            caps.push("privileged=true (host.privileged)");
+        if (caps.length > 0)
+            refused.set(name, caps);
+    }
+    return refused;
+}
+/**
+ * The launch-time notice a provider without a scheduler owes for a declared
+ * `schedule` (D-51, PROVIDERS.md §10 item 8).
+ *
+ * States what *this provider* does, not what will happen to the app: a
+ * component may schedule itself — `catalog/drafts/diun` sets its own
+ * `DIUN_WATCH_SCHEDULE`, and nextcloud's `cron.sh` is a foreground `crond` —
+ * so claiming the job will not run would be false about those apps, and a
+ * warning that misstates the user's app is worse than the silence it replaces.
+ */
+export function scheduleWarning(component, schedule) {
+    return (`[${component}] declares \`schedule: ${schedule}\` — this provider will not ` +
+        "run it on a timer. If the component does not schedule itself, the job will not run.");
+}
+/**
+ * Remove every component this provider must refuse, and say so on stderr.
+ *
+ * The removal is the refusal (D-44, PROVIDERS.md §11): a component left in the
+ * map goes on to be installed, env-wired, registered with the process manager
+ * and started, so logging alone would have the provider assert a refusal it
+ * did not perform. Mutates `launch.components` for exactly that reason —
+ * everything downstream reads it.
+ *
+ * Returns "none-left" when nothing survives, so the caller can fail rather than
+ * report success over an empty set.
+ */
+export function applyHostCapabilityRefusals(launch) {
+    const refused = refusedHostCapabilities(launch);
+    for (const [name, caps] of refused) {
+        console.error(`  Refused: ${name} requires host capabilities this provider cannot grant ` +
+            `(${caps.join("; ")}) — component not started`);
+    }
+    if (refused.size === 0)
+        return "ok";
+    launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => !refused.has(n)));
+    return Object.keys(launch.components).length === 0 ? "none-left" : "ok";
+}
 export async function launchUp(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     // 1. Check prerequisites
@@ -38,7 +131,120 @@ export async function launchUp(opts = {}) {
         process.exit(1);
     }
     const launch = readLaunch(launchfileContent);
+    const allComponentNames = Object.keys(launch.components);
+    // Resolve component selector (#77) into its D-41 start-set: selected
+    // components + their transitive downward `depends_on` closure (and, by
+    // narrowing to that set, every closure member's `requires`). Narrowing
+    // launch.components here makes every downstream phase loop in launchUp honor
+    // the closure without per-loop edits — dropping it would hand back an app
+    // missing the very dependencies a selected component needs to start (D-16).
+    // down/status/env re-read the file, so they are unaffected.
+    const selection = selectionClosure(launch, opts.components ?? []);
+    if (selection.unknown.length > 0 || selection.resources.length > 0) {
+        console.error(`\nCannot select: ${[...selection.unknown, ...selection.resources].join(", ")}`);
+        for (const r of selection.resources) {
+            console.error(`  - "${r}" is a backing resource, not a component; select the component that requires it.`);
+        }
+        for (const u of selection.unknown) {
+            console.error(`  - "${u}" matches no component. Available: ${allComponentNames.join(", ")}`);
+        }
+        process.exit(1);
+    }
+    if (opts.components && opts.components.length > 0) {
+        const startSet = new Set(selection.start);
+        launch.components = Object.fromEntries(Object.entries(launch.components).filter(([n]) => startSet.has(n)));
+    }
+    // 2a. Host capabilities are granted or refused, never provisioned (D-44,
+    // PROVIDERS.md §11). This provider runs processes directly on the host and
+    // grants none of them, so a component with a required capability is
+    // DECLINED — removed from the map here so nothing downstream installs a
+    // runtime, wires env, registers with pm2, or starts it. Logging alone would
+    // leave the provider asserting a refusal it did not perform.
+    // Both spellings fold together so they land identically (§11 equivalence):
+    // the `host:` entry form and the legacy top-level block.
+    if (applyHostCapabilityRefusals(launch) === "none-left") {
+        console.error("Every selected component requires a host capability this provider cannot grant.");
+        process.exit(1);
+    }
+    // An optional capability is not refused — the component runs, degraded.
+    for (const [name, c] of Object.entries(launch.components)) {
+        for (const sup of c.supports ?? []) {
+            for (const [capability, value] of Object.entries(sup.host ?? {})) {
+                console.warn(`  Warning: ${name}: optional host capability ` +
+                    `${capability}=${String(value)} not granted — running degraded`);
+            }
+        }
+    }
     const componentNames = Object.keys(launch.components);
+    // 2b. Source-mode guard (D-38) — fail fast before provisioning anything.
+    // Run precedence is `dev` > `image` > `start`: a component runs from source
+    // when it declares `dev`, or a `start` with no `image`. An `image` without a
+    // `dev` override stays artifact-mode — which this source-only provider can't
+    // launch. If nothing is source-runnable, the app belongs on `launchfile up`.
+    const sourceRunnable = Object.values(launch.components).filter(isSourceRunnable);
+    if (sourceRunnable.length === 0) {
+        const hasImage = Object.values(launch.components).some((c) => c.image);
+        console.error("Nothing to run from source: no component declares `dev` (or a `start` without an `image`).");
+        console.error(hasImage
+            ? "This app runs from an image — use `launchfile up` to launch the built artifact."
+            : "Add a `dev` (or `start`) command to run it from source.");
+        process.exit(1);
+    }
+    // Mixed app: warn about artifact components (image, no `dev` override) that
+    // this source-only provider can't launch — they need `launchfile up`.
+    for (const [name, c] of Object.entries(launch.components)) {
+        if (!isSourceRunnable(c) && c.image) {
+            console.warn(`  ! [${name}] has an image and no \`dev\` override — runs as an artifact, ` +
+                "skipped in source mode; use `launchfile up` to run it.");
+        }
+        // PROVIDERS.md conformance rule 8 (D-51): a provider that does not
+        // execute `schedule` MUST say so at launch. Staying silent leaves an
+        // author believing a declared cron job is running — the one outcome
+        // worse than not supporting it. Wording stays start-agnostic: artifact
+        // components with a schedule reach this loop too, and they are skipped
+        // entirely in source mode.
+        if (c.schedule) {
+            console.warn(`  ! ${scheduleWarning(name, c.schedule)}`);
+        }
+    }
+    // 2c. Unsupplied `required:` environment variables (D-52, PROVIDERS.md §10
+    // rule 8, deploying branch). This provider's operator channel is the
+    // launching environment, read EXPLICITLY here — the `...process.env` spread
+    // on the pm2 registration below is incidental inheritance that never reaches
+    // `release` and is invisible to `env`, so it cannot serve as the channel.
+    // Values found are carried in `operatorEnv` and merged into `allEnvs` at
+    // step 12, which puts them on both `release` and `start` and makes them
+    // visible to `launch env`. Anything still missing fails HERE — before
+    // directories, resources, ports, runtimes, or processes exist. No prompt: a
+    // non-interactive invocation must fail by name, not hang on stdin.
+    const operatorEnv = {};
+    const missingRequired = [];
+    for (const [name, component] of Object.entries(launch.components)) {
+        // A `requires:` binding injects only when this provider can provision the
+        // resource behind it; `supports:` is provisioned only under --with-optional
+        // and is never credited (SPEC.md §Supports).
+        const arriving = new Set((component.requires ?? [])
+            .filter((req) => !req.host && getProvisioner(req.type))
+            .flatMap((req) => Object.keys(req.set_env ?? {})));
+        for (const { key, sensitive } of unsuppliedRequiredEnv(component, arriving)) {
+            const supplied = process.env[key];
+            if (supplied !== undefined) {
+                (operatorEnv[name] ??= {})[key] = supplied;
+                continue;
+            }
+            missingRequired.push({ component: name, key, sensitive });
+        }
+    }
+    if (missingRequired.length > 0) {
+        console.error(`\nCannot launch: ${missingRequired.length} required environment variable${missingRequired.length === 1 ? "" : "s"} had no value.`);
+        for (const { component, key, sensitive } of missingRequired) {
+            console.error(`  - ${component}: ${key}${sensitive ? " (sensitive)" : ""}`);
+        }
+        console.error("\nThe Launchfile declares them `required:` with no `default:`, `generator:`, or resource");
+        console.error("binding, so you supply them. Set them in the environment and run `up` again, e.g.");
+        console.error(`  ${missingRequired[0].key}=<value> launch up`);
+        process.exit(1);
+    }
     // 3. Load or init state
     let state = await loadState(projectDir);
     if (!state) {
@@ -52,6 +258,8 @@ export async function launchUp(opts = {}) {
     const resourceMap = {};
     for (const [_compName, component] of Object.entries(launch.components)) {
         for (const req of component.requires ?? []) {
+            if (req.host)
+                continue; // capability, not a backing service (D-44)
             const resourceName = req.name ?? req.type;
             if (resourceMap[resourceName])
                 continue; // Already provisioned
@@ -75,6 +283,8 @@ export async function launchUp(opts = {}) {
         // Optional supports resources
         if (opts.withOptional) {
             for (const sup of component.supports ?? []) {
+                if (sup.host)
+                    continue; // capability, not a backing service (D-44)
                 const resourceName = sup.name ?? sup.type;
                 if (resourceMap[resourceName])
                     continue;
@@ -134,16 +344,29 @@ export async function launchUp(opts = {}) {
     }
     // 10. Detect package manager
     const pm = await detectPackageManager(projectDir);
-    // 11. Create storage directories
+    // 11. Create storage directories, capturing each volume's resolved local path
+    // so it can be injected as $storage.<name>.path (D-39). Scoped per component.
+    const componentStorage = {};
     for (const [name, component] of Object.entries(launch.components)) {
-        await provisionStorage(component.storage, name, projectDir);
+        const volumeMap = await provisionStorage(component.storage, name, projectDir);
+        const storageCtx = {};
+        for (const [volName, localPath] of Object.entries(volumeMap)) {
+            storageCtx[volName] = { path: localPath };
+        }
+        componentStorage[name] = storageCtx;
     }
     // 12. Resolve env vars and write .env files
     const allEnvs = {};
     const isSingleComponent = componentNames.length === 1 && componentNames[0] === "default";
+    // Minted env-level generator values live in state (D-49) so a redeploy
+    // reuses them; saveState below (step 13) persists anything minted here.
+    const generatedEnv = (state.generatedEnv ??= {});
     for (const [name, component] of Object.entries(launch.components)) {
-        const env = resolveComponentEnv(component, context, resourceMap);
-        await resolveGenerators(component, env);
+        const { env } = resolveComponentEnv(component, context, resourceMap, componentStorage[name]);
+        await resolveGenerators(component, env, name, generatedEnv);
+        // Operator-supplied `required:` values (step 2c) join the resolved set, so
+        // they reach `release` and `start` alike and show up in `launch env`.
+        Object.assign(env, operatorEnv[name] ?? {});
         const port = componentPorts[name];
         if (port && !env.PORT) {
             env.PORT = String(port);
@@ -171,62 +394,75 @@ export async function launchUp(opts = {}) {
         printSummary(launch, componentPorts, resourceMap);
         return;
     }
-    // 14. Run build commands
+    // 14. Run source-mode prepare \u2014 `install ?? build` (D-38), on demand
     if (!opts.noBuild) {
         for (const [name, component] of Object.entries(launch.components)) {
-            const buildCmd = component.commands?.build?.command;
-            const cmd = buildCmd ?? pm?.installCommand;
+            const prepare = resolveSourcePrepareCommand(component);
+            const cmd = prepare?.command ?? pm?.installCommand;
             if (cmd) {
-                console.log(`  \u2193 Building${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-                await shell(cmd, {
-                    cwd: projectDir,
+                console.log(`  \u2193 Preparing${componentNames.length > 1 ? ` [${name}]` : ""}...`);
+                await shellScript(cmd, {
+                    cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
                     env: allEnvs[name],
+                    // Installs/compiles routinely exceed the 2-minute shell default;
+                    // honor a declared timeout, else allow 10 minutes.
+                    timeout: declaredTimeout(prepare?.timeout, `prepare [${name}]`) ?? 600_000,
                 });
             }
         }
     }
-    // 15. Run release commands (migrations)
+    // 15. Run release commands (migrations) \u2014 mode-invariant (D-38)
     for (const [name, component] of Object.entries(launch.components)) {
-        const releaseCmd = component.commands?.release?.command;
-        if (releaseCmd) {
+        const release = component.commands?.release;
+        if (release?.command) {
             console.log(`  \u2193 Running release${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-            await shell(releaseCmd, {
-                cwd: projectDir,
+            await shellScript(release.command, {
+                cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
                 env: allEnvs[name],
+                timeout: declaredTimeout(release.timeout, `release [${name}]`),
             });
         }
     }
-    // 16. Start all components
+    // 16. Run components from source \u2014 `dev` over `start` (D-38; this provider ignores `image`)
     process.stdout.write(`  \u2193 Starting services...`);
     const pm2 = new ProcessManager(projectDir);
     for (const [name, component] of Object.entries(launch.components)) {
-        const startCmd = component.commands?.start?.command;
-        if (!startCmd) {
-            console.warn(`\n  ! [${name}] No start command — skipping`);
+        // Resolve the source-mode run command (D-38 precedence `dev` > `image` >
+        // `start`). Artifact components (image, no `dev` override) resolve to
+        // undefined — they were warned by the guard; skip them.
+        const startCmd = resolveSourceRunCommand(component)?.command;
+        if (!startCmd)
             continue;
-        }
         pm2.register(name, {
             command: startCmd,
             env: { ...process.env, ...allEnvs[name] },
-            cwd: projectDir,
+            cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
             dependsOn: component.depends_on,
             health: component.health,
             port: componentPorts[name],
         });
     }
     // Handle Ctrl+C gracefully
+    const finalState = state;
     process.on("SIGINT", async () => {
         console.log("\n\nShutting down...");
         await pm2.stopAll();
-        await saveState(projectDir, state);
+        // Processes are now dead; clear the recorded pids so a later `launch down`
+        // doesn't try to signal stale (and possibly recycled) pids.
+        finalState.processes = {};
+        await saveState(projectDir, finalState);
         process.exit(0);
     });
     await pm2.startAll();
     console.log("");
     console.log(`  \u2713 All components started`);
+    // Record spawned pids so `launch down` can stop them from another shell or
+    // after this foreground session ends (closes #49). Backward compatible: the
+    // field is optional and absent in pre-existing state files.
+    state.processes = pm2.getRecordedProcesses();
     // 17. Print summary
     printSummary(launch, componentPorts, resourceMap);
-    // Save final state
+    // Save final state (now including recorded pids)
     await saveState(projectDir, state);
 }
 function printSummary(launch, ports, _resources) {
@@ -244,6 +480,35 @@ export async function launchDown(opts = {}) {
         console.log("No active launch state found.");
         return;
     }
+    // Stop recorded app processes (closes #49). Backward compatible: state files
+    // written before pid persistence simply have no `processes`, so we skip this
+    // and behave exactly as before (resources-only down).
+    const recorded = state.processes ?? {};
+    if (Object.keys(recorded).length > 0) {
+        console.log("Stopping app processes...");
+        const outcomes = await stopRecordedProcesses(recorded);
+        for (const o of outcomes) {
+            switch (o.result) {
+                case "stopped":
+                    console.log(`  Stopped ${o.component}`);
+                    break;
+                case "already-dead":
+                    console.log(`  ${o.component} was not running`);
+                    break;
+                case "identity-mismatch":
+                    console.log(`  Skipped ${o.component} (pid recycled — left untouched)`);
+                    break;
+                case "error":
+                    console.log(`  Failed to stop ${o.component}: ${o.error}`);
+                    break;
+            }
+        }
+        // Clear recorded pids now that we've handled them.
+        state.processes = {};
+        if (!opts.destroy) {
+            await saveState(projectDir, state);
+        }
+    }
     if (opts.destroy) {
         console.log("Destroying resources...");
         for (const [name, resourceState] of Object.entries(state.resources)) {
@@ -262,6 +527,11 @@ export async function launchDown(opts = {}) {
         console.log("Stopped. Resources are still running (use --destroy to remove them).");
     }
 }
+// --detach is intentionally left as a follow-up: persisting pids (this PR) is
+// the prerequisite for it. With pids now recorded and a working cross-session
+// `down`, detach becomes "spawn detached + unref + don't install the SIGINT
+// foreground loop, then return" — a self-contained change best done separately
+// so the kill-path fix lands reviewable on its own.
 export async function launchStatus(opts = {}) {
     const projectDir = opts.projectDir ?? process.cwd();
     const state = await loadState(projectDir);
@@ -307,18 +577,57 @@ export async function launchEnv(opts = {}) {
     }
     const appProperties = computeAppProperties(launch, state.ports);
     const context = buildResolverContext(resourceMap, state.ports, state.secrets, appProperties);
+    // `env` reports what the running app has, so it reads minted generator
+    // values from the same store `up` persists to (D-49). A value can still be
+    // minted here — a generator declared after the last `up` — and then it is
+    // persisted below, before printing, so `up`, `env`, and `bootstrap` all
+    // keep answering with the same value.
+    const generatedEnv = (state.generatedEnv ??= {});
+    let minted = false;
+    const resolvedEnvs = [];
     for (const [name, component] of Object.entries(launch.components)) {
         if (opts.component && name !== opts.component)
             continue;
-        const env = resolveComponentEnv(component, context, resourceMap);
-        await resolveGenerators(component, env);
+        // Resolved storage paths (D-39) — computed, not provisioned (no mkdir):
+        // `launchfile env` only prints, and the dirs already exist from `up`.
+        const storageCtx = {};
+        for (const [volName, localPath] of Object.entries(storagePaths(component.storage, name, projectDir))) {
+            storageCtx[volName] = { path: localPath };
+        }
+        const { env, unsupplied } = resolveComponentEnv(component, context, resourceMap, storageCtx);
+        minted = (await resolveGenerators(component, env, name, generatedEnv)) || minted;
+        // The operator channel `up` reads (the launching environment) answers here
+        // too, so a var supplied at launch time prints as a real value rather than
+        // being reported missing.
+        for (const { key } of unsupplied) {
+            const supplied = process.env[key];
+            if (supplied !== undefined)
+                env[key] = supplied;
+        }
         const port = state.ports[name];
         if (port && !env.PORT)
             env.PORT = String(port);
+        resolvedEnvs.push([name, env, unsupplied]);
+    }
+    if (minted) {
+        await saveState(projectDir, state);
+    }
+    for (const [name, env, unsupplied] of resolvedEnvs) {
         console.log(`\n# ${name}`);
         for (const [key, value] of Object.entries(env).sort(([a], [b]) => a.localeCompare(b))) {
             console.log(`${key}=${value}`);
         }
+        // PROVIDERS.md §10 rule 8, `env` branch: report an unsupplied required var
+        // rather than dropping it — this is where an operator comes to find out
+        // what is missing. It goes out as a `#` comment, never a bare `KEY=` line,
+        // because this output is designed to be `eval`'d (§2): a bare line would
+        // export an empty value and re-create the failure the rule exists to stop.
+        for (const { key, sensitive } of unsupplied.sort((a, b) => a.key.localeCompare(b.key))) {
+            if (env[key] !== undefined)
+                continue;
+            console.log(`# ${key}: unsupplied — required, no default/generator/binding` +
+                `${sensitive ? ", sensitive" : ""}. Supply it in the environment.`);
+        }
     }
 }
 //# sourceMappingURL=provider.js.map

package/dist/redact.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Secret redaction for anything this provider prints or embeds in an error.
+ *
+ * Two independent layers, because either alone leaves a hole:
+ *
+ * 1. A registry of exact secret values. Every generated secret, every
+ *    persisted `state.secrets` entry, and every resource password registers
+ *    itself at creation/load time; `redactSecrets` then scrubs those literals
+ *    out of any string on its way to stdout/stderr or an Error message.
+ * 2. A pattern scrub for credentials embedded in URLs
+ *    (`scheme://user:pass@host`), which catches secrets that never passed
+ *    through this provider — e.g. a connection string written literally in a
+ *    Launchfile `env:` value and interpolated into a bootstrap command.
+ *
+ * The registry is process-global on purpose: a command string is assembled in
+ * one module and printed in another, so the scrub has to be reachable from the
+ * sink without threading a context object through every call site.
+ */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Register a value this provider *inferred* is a secret: one it minted itself,
+ * or read back out of its own state. Values below `MIN_SECRET_LENGTH` are
+ * dropped — nothing declared them sensitive, so a coincidental match would
+ * corrupt output for no gain.
+ */
+export declare function registerSecret(value: string | undefined | null): void;
+/**
+ * Register a value something *declared* is a secret: an `env:` literal marked
+ * `sensitive: true` (D-18), or a value handed over on the operator channel
+ * (D-52). No length floor applies.
+ *
+ * `sensitive: true` on a six-digit PIN is the author stating that value must be
+ * masked. Dropping it for being short writes the PIN to disk in plaintext
+ * (CWE-532) — the exact failure this registry exists to prevent. Honouring the
+ * declaration costs an over-redacted diagnostic where the value also occurs by
+ * chance, which is recoverable; the alternative is a leaked credential, which
+ * is not.
+ *
+ * The empty string is rejected: it is not a credential, and an empty separator
+ * would splice `[REDACTED]` between every character of the text.
+ */
+export declare function registerDeclaredSecret(value: string | undefined | null): void;
+/** Register many secret values at once. Non-string entries are ignored. */
+export declare function registerSecrets(values: Iterable<string | undefined | null>): void;
+/** Drop every registered secret. Exists for test isolation. */
+export declare function clearRegisteredSecrets(): void;
+/**
+ * Scrub registered secrets and URL-embedded credentials out of `text`.
+ *
+ * Longest registered values are replaced first so that a secret which is a
+ * substring of another (a password inside its own connection URL) cannot leave
+ * a partial value behind.
+ */
+export declare function redactSecrets(text: string): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -0,0 +1,92 @@
+/**
+ * Secret redaction for anything this provider prints or embeds in an error.
+ *
+ * Two independent layers, because either alone leaves a hole:
+ *
+ * 1. A registry of exact secret values. Every generated secret, every
+ *    persisted `state.secrets` entry, and every resource password registers
+ *    itself at creation/load time; `redactSecrets` then scrubs those literals
+ *    out of any string on its way to stdout/stderr or an Error message.
+ * 2. A pattern scrub for credentials embedded in URLs
+ *    (`scheme://user:pass@host`), which catches secrets that never passed
+ *    through this provider — e.g. a connection string written literally in a
+ *    Launchfile `env:` value and interpolated into a bootstrap command.
+ *
+ * The registry is process-global on purpose: a command string is assembled in
+ * one module and printed in another, so the scrub has to be reachable from the
+ * sink without threading a context object through every call site.
+ */
+export const REDACTED = "[REDACTED]";
+/**
+ * Values shorter than this are not registered *by inference*. Short strings
+ * appear inside unrelated text by coincidence, and scrubbing them would corrupt
+ * the output it is meant to protect. Every secret this provider mints is far
+ * longer, so the floor never binds on a minted value.
+ *
+ * The floor is a heuristic, and a heuristic does not overrule an explicit
+ * declaration — see `registerDeclaredSecret`.
+ */
+const MIN_SECRET_LENGTH = 8;
+const registry = new Set();
+/**
+ * Register a value this provider *inferred* is a secret: one it minted itself,
+ * or read back out of its own state. Values below `MIN_SECRET_LENGTH` are
+ * dropped — nothing declared them sensitive, so a coincidental match would
+ * corrupt output for no gain.
+ */
+export function registerSecret(value) {
+    if (typeof value !== "string")
+        return;
+    if (value.length < MIN_SECRET_LENGTH)
+        return;
+    registry.add(value);
+}
+/**
+ * Register a value something *declared* is a secret: an `env:` literal marked
+ * `sensitive: true` (D-18), or a value handed over on the operator channel
+ * (D-52). No length floor applies.
+ *
+ * `sensitive: true` on a six-digit PIN is the author stating that value must be
+ * masked. Dropping it for being short writes the PIN to disk in plaintext
+ * (CWE-532) — the exact failure this registry exists to prevent. Honouring the
+ * declaration costs an over-redacted diagnostic where the value also occurs by
+ * chance, which is recoverable; the alternative is a leaked credential, which
+ * is not.
+ *
+ * The empty string is rejected: it is not a credential, and an empty separator
+ * would splice `[REDACTED]` between every character of the text.
+ */
+export function registerDeclaredSecret(value) {
+    if (typeof value !== "string" || value === "")
+        return;
+    registry.add(value);
+}
+/** Register many secret values at once. Non-string entries are ignored. */
+export function registerSecrets(values) {
+    for (const value of values)
+        registerSecret(value);
+}
+/** Drop every registered secret. Exists for test isolation. */
+export function clearRegisteredSecrets() {
+    registry.clear();
+}
+// `scheme://user:password@host` — the password group is everything between the
+// first `:` after the userinfo and the `@`. Userinfo cannot contain `/`, `@`,
+// or whitespace, which bounds the match to a single URL.
+const CREDENTIAL_URL = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/:@]+:)([^\s/@]+)(@)/g;
+/**
+ * Scrub registered secrets and URL-embedded credentials out of `text`.
+ *
+ * Longest registered values are replaced first so that a secret which is a
+ * substring of another (a password inside its own connection URL) cannot leave
+ * a partial value behind.
+ */
+export function redactSecrets(text) {
+    let out = text;
+    const values = [...registry].sort((a, b) => b.length - a.length);
+    for (const value of values) {
+        out = out.split(value).join(REDACTED);
+    }
+    return out.replace(CREDENTIAL_URL, `$1${REDACTED}$3`);
+}
+//# sourceMappingURL=redact.js.map

package/dist/resources/identifiers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Guards for values that reach a SQL statement by interpolation.
+ *
+ * On a first run these values are safe by construction: the database and user
+ * names derive from a schema-validated app name, and `generatePassword()`
+ * emits base64url. Every later run reuses whatever `.launchfile/state.json`
+ * holds, and `loadState()` (state.ts) `JSON.parse`s that file with no
+ * validation. The file sits inside the cloned repo, so on the reuse path every
+ * value below is attacker-controlled.
+ *
+ * Argv execution keeps the shell out of these commands; these checks keep the
+ * SQL parser out of them. Both are needed: `mysql -e` runs `;`-separated
+ * statements and connects as root, so a quote that escapes an identifier or a
+ * password literal is a full statement injection with no shell involved.
+ */
+/** Alphanumeric + underscore — safe as a SQL identifier and as a shell arg. */
+export declare const SAFE_IDENTIFIER: RegExp;
+/** base64url, the exact alphabet `generatePassword()` emits. No quote fits. */
+export declare const SAFE_PASSWORD: RegExp;
+export declare function assertSafeIdentifier(value: string, label: string): void;
+export declare function assertSafePassword(value: string): void;
+//# sourceMappingURL=identifiers.d.ts.map