@launchfile/macos-dev 0.3.0 → 0.4.0

package/dist/health.js

@@ -1,23 +1,17 @@
 /**
  * Health check polling for components.
  */
-import { shell } from "./shell.js";
-/** Parse a duration string like "30s", "1m", "500ms" to milliseconds */
+import { parseDurationMs } from "@launchfile/sdk";
+import { shellScript } from "./shell.js";
+/**
+ * Parse a health duration against the ratified grammar (D-48). Throws on an
+ * unparseable value — PROVIDERS.md §10.10 forbids silently substituting a
+ * default, and the previous local parser did exactly that in the worst
+ * possible way: it accepted no `h` unit and returned 0, so a spec-valid
+ * `interval: "1h"` became a zero-length poll that could never pass.
+ */
 export function parseDuration(duration) {
-    const match = /^(\d+)(ms|s|m)$/.exec(duration);
-    if (!match)
-        return 0;
-    const value = Number.parseInt(match[1], 10);
-    switch (match[2]) {
-        case "ms":
-            return value;
-        case "s":
-            return value * 1000;
-        case "m":
-            return value * 60_000;
-        default:
-            return 0;
-    }
+    return parseDurationMs(duration);
 }
 /**
  * Wait for a component to become healthy.
@@ -45,7 +39,7 @@ export async function waitForHealthy(name, health, port, overallTimeout = 60_000
                 }
             }
             else if (health.command) {
-                await shell(health.command, { timeout: checkTimeout, silent: true });
+                await shellScript(health.command, { timeout: checkTimeout, silent: true });
                 console.log(`  [${name}] Healthy`);
                 return true;
             }

package/dist/prereqs.js

@@ -6,11 +6,11 @@ export async function checkPrereqs() {
     const missing = [];
     const warnings = [];
     // Homebrew is required
-    if (!(await shellOk("which brew"))) {
+    if (!(await shellOk("which", ["brew"]))) {
         missing.push("Homebrew — install from https://brew.sh");
     }
     // Git is required (for cloning)
-    if (!(await shellOk("which git"))) {
+    if (!(await shellOk("which", ["git"]))) {
         missing.push("git — install via: brew install git");
     }
     return {

package/dist/process-manager.js

@@ -8,6 +8,7 @@ import { spawn } from "node:child_process";
 import { createWriteStream, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { waitForHealthy } from "./health.js";
+import { redactSecrets } from "./redact.js";
 // ANSI colors for log prefixing
 const COLORS = [
     "\x1b[36m", // cyan
@@ -89,7 +90,7 @@ export class ProcessManager {
             // For "started" condition, the process is already spawned by the time we get here
         }
         proc.status = "starting";
-        console.log(`  [${name}] Starting: ${proc.command}`);
+        console.log(`  [${name}] Starting: ${redactSecrets(proc.command)}`);
         const logFile = createWriteStream(join(this.logDir, `${name}.log`), { flags: "a" });
         const colorIdx = [...this.processes.keys()].indexOf(name) % COLORS.length;
         const color = COLORS[colorIdx];

package/dist/provider.d.ts

@@ -4,16 +4,14 @@
  * Reads a Launchfile, provisions resources, resolves env vars,
  * installs runtimes, and starts all components.
  */
-import { type NormalizedComponent } from "@launchfile/sdk";
+import { type NormalizedLaunch, type NormalizedComponent } from "@launchfile/sdk";
 /**
- * Source-mode run resolution (D-38, precedence `dev` > `image` > `start`).
- * This provider runs apps from source. A component is source-runnable 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.
+ * 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 declare function isSourceRunnable(component: NormalizedComponent): boolean;
-/** The command run from source, or undefined if the component resolves to its artifact. */
-export declare function sourceRunCommand(component: NormalizedComponent): string | undefined;
 export interface LaunchUpOpts {
     withOptional?: boolean;
     noBuild?: boolean;
@@ -29,6 +27,40 @@ export interface LaunchUpOpts {
      */
     components?: string[];
 }
+/**
+ * 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 declare function refusedHostCapabilities(launch: NormalizedLaunch): Map<string, string[]>;
+/**
+ * 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 declare function scheduleWarning(component: string, schedule: string): string;
+/**
+ * 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 declare function applyHostCapabilityRefusals(launch: NormalizedLaunch): "ok" | "none-left";
 export declare function launchUp(opts?: LaunchUpOpts): Promise<void>;
 export declare function launchDown(opts?: {
     destroy?: boolean;

package/dist/provider.js

@@ -6,24 +6,7 @@
  */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { readLaunch, selectionClosure } from "@launchfile/sdk";
-/**
- * Source-mode run resolution (D-38, precedence `dev` > `image` > `start`).
- * This provider runs apps from source. A component is source-runnable 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.
- */
-export function isSourceRunnable(component) {
-    return Boolean(component.commands?.dev || (component.commands?.start && !component.image));
-}
-/** The command run from source, or undefined if the component resolves to its artifact. */
-export function sourceRunCommand(component) {
-    if (component.commands?.dev?.command)
-        return component.commands.dev.command;
-    if (component.image)
-        return undefined; // image, no `dev` override → artifact
-    return component.commands?.start?.command;
-}
+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";
@@ -34,8 +17,99 @@ import { detectPackageManager } from "./lockfile-detect.js";
 import { provisionStorage, storagePaths } from "./storage.js";
 import { ProcessManager } from "./process-manager.js";
 import { stopRecordedProcesses } from "./process-stopper.js";
-import { shell } from "./shell.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
@@ -80,6 +154,27 @@ export async function launchUp(opts = {}) {
         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
@@ -102,6 +197,53 @@ export async function launchUp(opts = {}) {
             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);
@@ -116,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
@@ -139,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;
@@ -212,9 +358,15 @@ export async function launchUp(opts = {}) {
     // 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, componentStorage[name]);
-        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);
@@ -245,16 +397,16 @@ export async function launchUp(opts = {}) {
     // 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 prepare = component.commands?.install ?? component.commands?.build;
+            const prepare = resolveSourcePrepareCommand(component);
             const cmd = prepare?.command ?? pm?.installCommand;
             if (cmd) {
                 console.log(`  \u2193 Preparing${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-                await shell(cmd, {
+                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: prepare?.timeout ? parseDuration(prepare.timeout) : 600_000,
+                    timeout: declaredTimeout(prepare?.timeout, `prepare [${name}]`) ?? 600_000,
                 });
             }
         }
@@ -264,10 +416,10 @@ export async function launchUp(opts = {}) {
         const release = component.commands?.release;
         if (release?.command) {
             console.log(`  \u2193 Running release${componentNames.length > 1 ? ` [${name}]` : ""}...`);
-            await shell(release.command, {
+            await shellScript(release.command, {
                 cwd: join(projectDir, component.source ?? component.build?.context ?? "."),
                 env: allEnvs[name],
-                timeout: release.timeout ? parseDuration(release.timeout) : undefined,
+                timeout: declaredTimeout(release.timeout, `release [${name}]`),
             });
         }
     }
@@ -278,7 +430,7 @@ export async function launchUp(opts = {}) {
         // 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 = sourceRunCommand(component);
+        const startCmd = resolveSourceRunCommand(component)?.command;
         if (!startCmd)
             continue;
         pm2.register(name, {
@@ -425,6 +577,14 @@ 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;
@@ -434,15 +594,40 @@ export async function launchEnv(opts = {}) {
         for (const [volName, localPath] of Object.entries(storagePaths(component.storage, name, projectDir))) {
             storageCtx[volName] = { path: localPath };
         }
-        const env = resolveComponentEnv(component, context, resourceMap, storageCtx);
-        await resolveGenerators(component, env);
+        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