koppler 0.0.0-stage → 0.0.2

package/dist/engine/branch.js

@@ -0,0 +1,194 @@
+// Switches an app's clone to the branch the board asks for, the way the user chose on the card for uncommitted changes:
+// set aside (stashed under a Koppler label, back on Stop) or taken along. Every switch is logged, so it can be undone.
+// Usage: koppler switch <app> <branch> [--set-aside | --take-along]
+//        koppler switch <app> --back
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fail } from "../failure.js";
+import { readData } from "../data.js";
+import { updateActions } from "./actions.js";
+const said = (failure) => (failure.stderr || failure.message || '').trim();
+const git = (repo, ...args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+function tryGit(repo, ...args) {
+    try {
+        return { ok: true, out: git(repo, ...args) };
+    }
+    catch (error) {
+        return { ok: false, out: said(error) };
+    }
+}
+const firstLine = (text) => text.split('\n')[0] ?? '';
+/** How many files the clone has changed and not committed, new ones included. */
+const changed = (repo) => git(repo, 'status', '--porcelain').split('\n').filter(Boolean).length;
+const changes = (count) => `${String(count)} uncommitted ${count === 1 ? 'change' : 'changes'}`;
+const head = (repo) => git(repo, 'rev-parse', '--abbrev-ref', 'HEAD');
+const named = (from, detached) => (detached ? `commit ${from.slice(0, 7)}` : from);
+/** The stash entry Koppler made under this label, as git names it (stash@{n}). */
+function stashOf(repo, label) {
+    const entries = git(repo, 'stash', 'list', '--format=%gd%x09%s').split('\n');
+    return entries.map(line => line.split('\t')).find(([, subject]) => subject?.endsWith(label))?.[0];
+}
+/** A git failure nobody foresaw (the clone is gone, not a repository) is an answer, not a crash in the middle of a Stop. */
+function safely(app, work) {
+    try {
+        return work();
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.status === undefined && failure.spawnargs === undefined)
+            throw error;
+        return { error: `${app}: ${said(failure).split('\n').pop() ?? ''}` };
+    }
+}
+const isSwitch = (app, to) => (action) => action.kind === 'checkout' && action.app === app && (to === undefined || action.to === to);
+const forget = (logFile, app, to) => {
+    updateActions(logFile, log => {
+        const at = log.findLastIndex(isSwitch(app, to));
+        if (at >= 0)
+            log.splice(at, 1);
+    });
+};
+export const switchTo = ({ app, repo, to, how, logFile }) => safely(app, () => {
+    // A clone on a commit instead of a branch goes back to that commit.
+    const detached = head(repo) === 'HEAD';
+    const from = detached ? git(repo, 'rev-parse', 'HEAD') : head(repo);
+    const was = named(from, detached);
+    if (from === to)
+        return { message: `${app} is already on ${to}` };
+    // Given to git as an argument: never something git would read as an option.
+    if (to.startsWith('-'))
+        return { error: `${to} is not a branch name` };
+    const dirty = changed(repo);
+    if (dirty && !how)
+        return {
+            error: `${app} has ${changes(dirty)} on ${was}: choose --set-aside or --take-along (the canvas asks this on the card)`,
+        };
+    const label = dirty && how === 'set-aside' ? `koppler: ${app} on ${was} while it runs ${to}` : null;
+    // Logged before anything changes, so a crash part-way still leaves Stop an entry to undo.
+    const entry = {
+        kind: 'checkout',
+        app,
+        repo,
+        from,
+        to,
+        ...(detached && { detached: true }),
+        ...(label && { stash: label }),
+        ...(dirty > 0 && how === 'take-along' && { carried: true }),
+    };
+    updateActions(logFile, log => void log.push(entry));
+    if (label) {
+        const aside = tryGit(repo, 'stash', 'push', '--include-untracked', '-m', label);
+        if (!aside.ok) {
+            forget(logFile, app, to);
+            return { error: `${app}'s changes could not be set aside: ${firstLine(aside.out)}` };
+        }
+    }
+    const switched = tryGit(repo, 'switch', to);
+    if (!switched.ok) {
+        // What was set aside comes straight back; the entry goes once it has.
+        const ref = label ? stashOf(repo, label) : undefined;
+        const back = ref ? tryGit(repo, 'stash', 'pop', ref).ok : true;
+        if (back)
+            forget(logFile, app, to);
+        const clash = how === 'take-along' && /overwritten|conflict/i.test(switched.out);
+        const why = clash
+            ? `${app}'s changes clash with ${to}; set them aside instead (--set-aside)`
+            : `${app} could not switch to ${to}: ${firstLine(switched.out)}`;
+        return { error: why + (back ? '' : `; your set-aside changes stay in the stash as "${label ?? ''}"`) };
+    }
+    const carried = label
+        ? `, your ${changes(dirty)} ${dirty === 1 ? 'is' : 'are'} set aside until Stop`
+        : dirty
+            ? `, your ${changes(dirty)} came along`
+            : '';
+    return { message: `${app}: ${was} -> ${to}${carried}` };
+});
+/**
+ * Brings back what was set aside under `stash`, onto a clean clone only, so a clash can be undone without touching
+ * anything else. Gives the words to add to the message, or the reason it could not.
+ */
+function restoreStash(app, repo, stash, was) {
+    const ref = stashOf(repo, stash);
+    if (!ref)
+        return { note: ', your set-aside changes were taken back already' };
+    if (changed(repo))
+        return {
+            error: `${app} is back on ${was} with new changes; the ones set aside wait in the stash as "${stash}" (git stash pop, once these are committed)`,
+        };
+    const untracked = tryGit(repo, 'ls-tree', '-r', '--name-only', '-z', `${ref}^3`);
+    if (tryGit(repo, 'stash', 'pop', ref).ok)
+        return { note: ', your set-aside changes are back' };
+    // Git leaves a clashing change half applied and keeps the stash. The clone goes back to clean; the changes stay in
+    // the stash.
+    git(repo, 'reset', '--hard', '-q');
+    for (const file of untracked.ok ? untracked.out.split('\0').filter(Boolean) : [])
+        fs.rmSync(path.join(repo, file), { force: true });
+    return {
+        error: `${app} is back on ${was}, but your set-aside changes clash with what it holds now. They are safe in the stash as "${stash}": take them back with git stash pop and settle the clash there`,
+    };
+}
+/**
+ * Undoes the app's latest switch. The entry leaves the log only once the clone is where it was and the set-aside
+ * changes are back, so Stop can be run again.
+ */
+export const switchBack = ({ app, logFile }) => safely(app, () => {
+    const entry = updateActions(logFile, log => log.findLast(isSwitch(app)));
+    if (!entry)
+        return { message: `${app}: no branch switch to undo` };
+    const { repo, from, to, stash, carried, detached } = entry;
+    const was = named(from, detached);
+    if (!fs.existsSync(repo))
+        return { error: `${app}'s clone is no longer at ${repo}, so it could not be switched back to ${was}` };
+    const there = detached ? head(repo) === 'HEAD' && git(repo, 'rev-parse', 'HEAD') === from : head(repo) === from;
+    const now = head(repo);
+    if (!there && now !== to) {
+        // The user moved the clone on since: it stays where they put it, and the switch is no longer Koppler's to undo.
+        forget(logFile, app, to);
+        const where = now === 'HEAD' ? 'the commit you checked out' : now;
+        const aside = stash ? `; your set-aside changes wait in the stash as "${stash}"` : '';
+        return { message: `${app}: left on ${where}, where you moved it; not switched back to ${was}${aside}` };
+    }
+    if (!there) {
+        const dirty = changed(repo);
+        // Changes made while it ran stay the user's: switching over them is their call, unless they came along in the
+        // first place.
+        if (dirty && !carried)
+            return {
+                error: `${app} has ${String(dirty)} new uncommitted ${dirty === 1 ? 'change' : 'changes'} on ${to}; it stays there until they are committed or set aside`,
+            };
+        const switched = tryGit(repo, 'switch', ...(detached ? ['--detach'] : []), from);
+        if (!switched.ok)
+            return { error: `${app} could not switch back to ${was}: ${firstLine(switched.out)}` };
+    }
+    const restored = stash ? restoreStash(app, repo, stash, was) : { note: '' };
+    if ('error' in restored)
+        return restored;
+    forget(logFile, app, to);
+    return { message: `${app}: back on ${was}${restored.note}` };
+});
+/** The clone of an app on this machine, as the last sync found it. */
+function cloneOf(app) {
+    const apps = readData('local')?.['apps'];
+    return apps?.[app]?.path;
+}
+export function switchCommand(args, { temp }) {
+    const [app, to] = args.filter(arg => !arg.startsWith('--'));
+    if (!app)
+        fail('usage: koppler switch <app> <branch> [--set-aside | --take-along] | koppler switch <app> --back');
+    const logFile = path.join(temp, 'actions.json');
+    let outcome;
+    if (args.includes('--back'))
+        outcome = switchBack({ app, logFile });
+    else {
+        const repo = cloneOf(app) ?? fail(`${app} has no clone on this Mac (koppler sync)`);
+        if (!to)
+            fail('usage: koppler switch <app> <branch> [--set-aside | --take-along]');
+        const how = args.includes('--set-aside') ? 'set-aside' : args.includes('--take-along') ? 'take-along' : null;
+        outcome = switchTo({ app, repo, to, how, logFile });
+    }
+    if (outcome.error !== undefined)
+        fail(outcome.error);
+    console.log(outcome.message);
+}
+//# sourceMappingURL=branch.js.map

package/dist/engine/branch.js.map

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

package/dist/engine/browser-console.js

@@ -0,0 +1,45 @@
+// A web app set to show its browser console on its card: when it starts, its page loads the canvas server's console
+// script, through one line added to its HTML entry file. The line is a temporary change: Stop takes it out.
+import fs from 'node:fs';
+import path from 'node:path';
+import { consoleKey } from "../server/browser-console.js";
+import { tempDir } from "../paths.js";
+import { readActions, updateActions } from "./actions.js";
+import { insideClone } from "./recipes.js";
+/** Adds the script line to the app's HTML file, logged so Stop undoes it; says what it did, or why not. */
+export function showBrowserConsole(app, repo, file) {
+    const target = insideClone(repo, file);
+    if (!target)
+        return `${file} is not a file inside ${app}'s clone`;
+    let canvas;
+    try {
+        canvas = new URL(fs.readFileSync(path.join(tempDir(), 'canvas-url'), 'utf8').trim());
+    }
+    catch {
+        return 'the canvas is not running, so the browser console has nowhere to go';
+    }
+    let body;
+    try {
+        body = fs.readFileSync(target, 'utf8');
+    }
+    catch {
+        return `${file} is not in the clone`;
+    }
+    const line = `<script src="http://${canvas.host}/console.js?app=${app}&key=${consoleKey(app)}"></script>`;
+    if (body.includes(line))
+        return 'already shows its browser console';
+    const log = path.join(tempDir(), 'actions.json');
+    if (readActions(log).some(action => action.kind === 'edit' && action.file === target && action.after.includes('/console.js?')))
+        return 'already shows its browser console';
+    const at = body.match(/<\/head>/i)?.[0];
+    if (!at)
+        return `${file} has no </head> to put the console script before`;
+    // Logged before the file changes, so a crash part-way still leaves Stop an entry to undo.
+    const entry = { kind: 'edit', app, file: target, before: at, after: `${line}${at}` };
+    updateActions(log, list => {
+        list.push(entry);
+    });
+    fs.writeFileSync(target, body.replace(at, () => entry.after));
+    return 'shows its browser console on its card';
+}
+//# sourceMappingURL=browser-console.js.map

package/dist/engine/browser-console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-console.js","sourceRoot":"","sources":["../../src/engine/browser-console.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,4GAA4G;AAC5G,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAmB,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,2GAA2G;AAC3G,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,IAAY,EAAE,IAAY;IACxE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM;QAAE,OAAO,GAAG,IAAI,yBAAyB,GAAG,UAAU,CAAC;IAClE,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,qEAAqE,CAAC;IAC/E,CAAC;IACD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,sBAAsB,CAAC;IACvC,CAAC;IACD,MAAM,IAAI,GAAG,uBAAuB,MAAM,CAAC,IAAI,mBAAmB,GAAG,QAAQ,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC;IAC1G,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,mCAAmC,CAAC;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;IACjD,IACE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CACnB,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CACpG;QAED,OAAO,mCAAmC,CAAC;IAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE;QAAE,OAAO,GAAG,IAAI,kDAAkD,CAAC;IAC1E,0FAA0F;IAC1F,MAAM,KAAK,GAAe,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC;IACjG,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE;QACxB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,aAAa,CACd,MAAM,EACN,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CACpC,CAAC;IACF,OAAO,uCAAuC,CAAC;AACjD,CAAC"}

package/dist/engine/calls.js

@@ -0,0 +1,97 @@
+// Which app calls which, found from the deployed addresses the stack knows and the text of each clone.
+import { execFileSync } from 'node:child_process';
+import {} from "./config.js";
+/** Every deployed host each app is known by, from its own deployedUrl and from how other apps call it. */
+export function hostsByApp(stack) {
+    const hosts = {};
+    const add = (id, url) => {
+        try {
+            (hosts[id] ??= new Set()).add(new URL(url ?? '').hostname.toLowerCase());
+        }
+        catch {
+            // No address, or not one.
+        }
+    };
+    for (const [id, app] of Object.entries(stack.apps)) {
+        const envs = Object.values(app.envs ?? {});
+        add(id, app.deployedUrl);
+        for (const env of envs)
+            add(id, env['deployedUrl']);
+        for (const [callee, call] of Object.entries(app.consumes ?? {})) {
+            add(callee, call.deployed);
+            for (const env of envs)
+                add(callee, env['consumes']?.[callee]?.deployed);
+        }
+    }
+    return hosts;
+}
+/** A host that two apps share (one app's QA address pointing at another) cannot say which app is called, so it is left out. */
+export function hostOwners(stack) {
+    const owners = new Map();
+    for (const [id, hosts] of Object.entries(hostsByApp(stack)))
+        for (const host of hosts)
+            owners.set(host, [...(owners.get(host) ?? []), id]);
+    const unique = new Map();
+    for (const [host, ids] of owners)
+        if (ids.length === 1 && ids[0])
+            unique.set(host, ids[0]);
+    return { unique, shared: [...owners].filter(([, ids]) => ids.length > 1) };
+}
+/** Calls found in the caller's repo (a line naming another app's deployed host) that the stack does not list yet. */
+export function missingCalls(stack, grepRepo) {
+    const { unique } = hostOwners(stack);
+    const found = {};
+    for (const [caller, app] of Object.entries(stack.apps)) {
+        const hosts = [...unique].filter(([, owner]) => owner !== caller).map(([host]) => host);
+        if (!hosts.length)
+            continue;
+        for (const line of grepRepo(caller, hosts)) {
+            const host = hosts.find(one => line.toLowerCase().includes(one));
+            const callee = host && unique.get(host);
+            if (!callee || app.consumes?.[callee] || found[caller]?.[callee])
+                continue;
+            (found[caller] ??= {})[callee] = line.slice(0, 200);
+        }
+    }
+    return found;
+}
+// Tests, docs, lock files and one-off migration tools mention hosts without being the app's own calls.
+const NOT_CODE = [
+    '*.lock',
+    'package-lock.json',
+    '*.md',
+    '**/test/**',
+    '**/tests/**',
+    '**/*Test*/**',
+    '**/docs/**',
+    '**/*Migration*/**',
+].map(glob => `:(exclude,glob)${glob.includes('/') ? glob : '**/' + glob}`);
+const MAX_GREP = 16 * 1024 * 1024;
+export const lines = (text) => text.split('\n').filter(Boolean);
+export function grepClone(repo, hosts) {
+    const patterns = hosts.flatMap(host => ['-e', host]);
+    try {
+        return lines(execFileSync('git', ['-C', repo, 'grep', '-n', '-I', '-F', '-i', ...patterns, '--', ...NOT_CODE], {
+            encoding: 'utf8',
+            maxBuffer: MAX_GREP,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Every http(s) address written in a clone's code, as "file:line:url". */
+export function urlsInClone(repo) {
+    const find = ['grep', '-n', '-I', '-o', '-i', '-E', 'https?://[a-z0-9.-]+', '--', ...NOT_CODE];
+    try {
+        return lines(execFileSync('git', ['-C', repo, ...find], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: MAX_GREP,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=calls.js.map

package/dist/engine/calls.js.map

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

package/dist/engine/checks.js

@@ -0,0 +1,270 @@
+// What a stack needs on this Mac, checked when the stack loads. Koppler itself needs only git and Node.
+// The rest comes from the stack: the programs its kinds of app are started with, the programs its own commands call
+// (a tunnel's command, an AWS sign-in), and its `checks`, which are shell commands and so run only once the user approved them.
+// Usage: koppler doctor [--json]      run them and say what is missing
+//        koppler doctor --approve     show the stack's own check commands and allow them to run (again after they change)
+import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import { resolveExpressions } from "../core/expressions.js";
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJson } from "../json-files.js";
+import { of as kindOf } from "../core/kinds.js";
+import { isSignIn, signInOf } from "../core/sign-in.js";
+import { readData } from "../data.js";
+import { configDir, tempDir } from "../paths.js";
+const approvalsFile = () => path.join(configDir(), 'approved-checks.json');
+const TOOL = /^[A-Za-z0-9._+-]{1,64}$/;
+const text = (value, max = 300) => (typeof value === 'string' ? value.slice(0, max) : '');
+/** The checks a stack calls for. `safe` ones only ask whether a program is installed; the stack's own `checks` are shell. */
+export function checksFor(stack) {
+    const apps = Object.entries(stack?.apps ?? {});
+    const list = new Map();
+    const tool = (name, who, fix) => {
+        if (name === undefined || !TOOL.test(name))
+            return;
+        const check = list.get(name) ?? { name, tool: name, safe: true, for: [], fix: '' };
+        if (who && !check.for.includes(who))
+            check.for.push(who);
+        check.fix ||= typeof fix === 'string' ? fix : '';
+        list.set(name, check);
+    };
+    tool('git', 'Koppler', 'xcode-select --install');
+    tool('node', 'Koppler', 'Install Node 22 or newer');
+    for (const [, app] of apps.filter(([, one]) => !one.outside)) {
+        const kind = kindOf(app, stack);
+        for (const need of kind.needs ?? [])
+            tool(need.tool, kind.label, need.fix);
+        // Every environment's prerequisites: an AWS sign-in uses the aws program, a command is started by its first word.
+        const prereqs = [...(app.prereqs ?? []), ...Object.values(app.envs ?? {}).flatMap(env => env?.prereqs ?? [])];
+        for (const prereq of prereqs) {
+            const signIn = signInOf(stack, prereq);
+            if (signIn?.tool)
+                tool(signIn.tool, app.name ?? 'an app', stack?.install?.[signIn.tool]);
+            const first = text(prereq?.cmd).trim().split(/\s+/)[0];
+            if (first)
+                tool(first, prereq?.what ?? app.name ?? 'an app', stack?.install?.[first]);
+        }
+    }
+    for (const check of list.values())
+        check.fix ||= text(stack?.install?.[check.tool]) || `Install ${check.tool} and make sure it is on your PATH`;
+    const written = (Array.isArray(stack?.checks) ? stack.checks : []);
+    const own = written
+        .filter((check) => {
+        const { name, run } = (check ?? {});
+        return typeof name === 'string' && typeof run === 'string';
+    })
+        .slice(0, 50)
+        .map((check) => {
+        const kinds = check['kinds'];
+        return {
+            name: text(check.name, 80),
+            run: text(check.run, 2000),
+            ok: text(check['ok']),
+            fix: text(check['fix']) || 'This check of the stack fails',
+            safe: false,
+            ...(Array.isArray(kinds) && { kinds: kinds.filter(kind => typeof kind === 'string') }),
+        };
+    })
+        .filter(check => !check.kinds || apps.some(([, app]) => app.kind !== undefined && check.kinds?.includes(app.kind)));
+    return [...list.values(), ...own];
+}
+/**
+ * What the stack does not say for an environment other than the first: a tunnel the first one has, or how to get a
+ * secret there. Never filled in from the first environment: its hosts and secrets are another environment's.
+ */
+export function envGaps(stack, only) {
+    const [first, ...rest] = stack?.envs ?? [];
+    const gaps = [];
+    for (const env of rest.filter(one => !only || one === only))
+        for (const [id, app] of Object.entries(stack?.apps ?? {})) {
+            if (app.outside)
+                continue;
+            const own = app.envs?.[env] ?? {};
+            const label = env.toUpperCase();
+            const from = String(first).toUpperCase();
+            const name = app.name ?? id;
+            // Tunnels, sign-ins and hosts entries belong to one environment: each kind the first one has must be in this
+            // one's own list too.
+            const has = (kind) => (own.prereqs ?? []).some(prereq => prereq?.[kind]);
+            const signsIn = (own.prereqs ?? []).some(isSignIn);
+            const gap = (kind, what, detail) => gaps.push({ app: id, env, kind, name: what, detail });
+            for (const prereq of app.prereqs ?? []) {
+                if (prereq?.tunnel && !has('tunnel'))
+                    gap('tunnel', prereq.what ?? prereq.tunnel, `No ${label} tunnel for ${name}'s ${prereq.what ?? 'database'} (${from} uses ${prereq.tunnel})`);
+                const signIn = signInOf(stack, prereq);
+                if (signIn && !signsIn)
+                    gap('sign-in', prereq?.sso ?? prereq?.signIn, `No ${label} sign-in for ${name} (${from} uses ${prereq?.sso ? `the AWS profile ${prereq.sso}` : signIn.what})`);
+                if (prereq?.hosts && !has('hosts'))
+                    gap('hosts', prereq.hosts, `No ${label} hosts entry for ${name} (${from} uses ${prereq.hosts})`);
+            }
+            if (!own.secrets)
+                for (const secret of app.secrets ?? [])
+                    if (secret?.fetch)
+                        gap('secret', secret.env, `No steps for getting ${String(secret.env)} for ${name} on ${label}`);
+        }
+    return gaps;
+}
+/** Apps whose tunnels for `env` are missing: they must not borrow the first environment's. */
+export const missingTunnels = (stack, env) => [
+    ...new Set(envGaps(stack, env)
+        .filter(gap => gap.kind === 'tunnel')
+        .map(gap => gap.app)),
+];
+/**
+ * Everything in the stack that Koppler would run or write on this Mac, beyond the stack's facts: its own checks, the
+ * start commands it gives (per app, per environment, and per kind it defines), and the code changes it remembers.
+ * A shared stack can be edited by anyone on the team, so none of it happens until the user has seen exactly this list.
+ */
+export function stackCommands(stack) {
+    const out = [];
+    const add = (what, name, run) => {
+        if (typeof run === 'string' && run)
+            out.push({ what, name, run });
+    };
+    for (const check of checksFor(stack))
+        if (!check.safe)
+            add('check', check.name, check.run);
+    // Only the check: Koppler runs it. The login is shown for the user to run themselves.
+    for (const [name, signIn] of Object.entries(stack?.signIns ?? {})) {
+        add('sign-in check', name, signIn?.check);
+        // What it gives the apps it is for reaches them at start, so it is allowed with the rest.
+        for (const [setting, value] of Object.entries(signIn?.env ?? {}))
+            add('sign-in setting', `${name}: ${setting}`, value);
+    }
+    for (const [id, kind] of Object.entries(stack?.kinds ?? {})) {
+        add('start of every', `${id} app`, kind?.start);
+        add('stop of every', `${id} app`, kind?.stop);
+    }
+    for (const [id, app] of Object.entries(stack?.apps ?? {})) {
+        const name = app?.name ?? id;
+        add('start', name, app?.start);
+        for (const [env, own] of Object.entries(app?.envs ?? {}))
+            add(`start on ${env}`, name, own?.start);
+        for (const [key, command] of Object.entries(app?.commands ?? {}))
+            add(`command ${key} of`, name, command?.run);
+        const changes = (Array.isArray(app?.localChanges) ? app.localChanges : []);
+        for (const change of changes)
+            add('code change', `${name}, ${String(change?.['file'])}`, `${String(change?.['find'])}\n  becomes\n${String(change?.['replace'])}`);
+    }
+    return out;
+}
+/** Whether this app's start runs a command the stack wrote, on that environment. */
+export const startsFromStack = (stack, id, env) => {
+    const app = stack?.apps?.[id];
+    return !!(app && (app.start || app.envs?.[env]?.start || stack.kinds?.[app.kind ?? '']?.start));
+};
+/** Changes whenever a command of the stack's own changes; names and order of safe checks do not count. */
+export const fingerprint = (commands) => crypto
+    .createHash('sha256')
+    .update(JSON.stringify(commands.map(command => [command.what, command.name, command.run])))
+    .digest('hex');
+const approvals = () => {
+    try {
+        return JSON.parse(fs.readFileSync(approvalsFile(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+/** Approved when the stack runs nothing of its own, or the user approved exactly what it runs now. */
+export const approved = (source, stack) => {
+    const commands = stackCommands(stack);
+    return !commands.length || approvals()[source] === fingerprint(commands);
+};
+export function approve(source, stack) {
+    writeJson(approvalsFile(), { ...approvals(), [source]: fingerprint(stackCommands(stack)) });
+}
+export const APPROVE = 'koppler doctor --approve';
+const ran = (run, timeout) => {
+    try {
+        execFileSync('/bin/sh', ['-c', run], { stdio: 'ignore', ...(timeout && { timeout }) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const has = (tool) => ran(`command -v ${tool}`);
+const passes = (run) => ran(run, 20000);
+/** Runs what may run. A stack check that was not approved stays `pending`: listed, not run. */
+export function runChecks(stack, { source = stack?.source ?? '', exists = has, shell = passes } = {}) {
+    const ok = approved(source, stack);
+    const results = checksFor(stack).map((check) => {
+        if (check.safe) {
+            const base = { name: check.name, from: 'tool', ...(check.for.length && { for: check.for }) };
+            return exists(check.tool)
+                ? { ...base, state: 'ok', detail: 'installed' }
+                : { ...base, state: 'missing', detail: check.fix };
+        }
+        const base = { name: check.name, from: 'stack' };
+        if (!ok)
+            return { ...base, state: 'pending', detail: 'Waits for your approval: koppler doctor --approve' };
+        return shell(check.run)
+            ? { ...base, state: 'ok', detail: check.ok || 'ok' }
+            : { ...base, state: 'missing', detail: check.fix };
+    });
+    const gaps = envGaps(stack).map((gap) => ({
+        name: `${gap.app} ${gap.env}`,
+        from: 'stack',
+        state: 'gap',
+        detail: gap.detail,
+        app: gap.app,
+        env: gap.env,
+        kind: gap.kind,
+    }));
+    return [...results, ...gaps];
+}
+const WORD = { ok: 'ok', missing: 'MISSING', pending: 'PENDING', gap: 'GAP' };
+export function report(results) {
+    for (const result of results) {
+        const who = result.for?.length && result.state !== 'ok' ? ` (needed by ${result.for.join(', ')})` : '';
+        console.log(`${WORD[result.state].padEnd(8)} ${result.name.padEnd(14)} ${result.detail}${who}`);
+    }
+}
+const save = (stack, results) => {
+    const saved = { at: new Date().toISOString(), stack: stack.name ?? '', results };
+    writeJson(path.join(tempDir(), 'checks.json'), saved);
+};
+/** Runs the loaded stack's checks, prints them, and leaves the result for the canvas. False when something is missing. */
+export function checkStack({ quiet = false } = {}) {
+    const stack = resolveExpressions(readData('registry'));
+    if (!stack)
+        return true;
+    const results = runChecks(stack);
+    fs.mkdirSync(tempDir(), { recursive: true });
+    save(stack, results);
+    if (!quiet)
+        report(results);
+    return !results.some(result => result.state === 'missing');
+}
+/**
+ * The tools and the stack's own checks on this Mac, saved for the canvas. With `approve`, the stack's check commands
+ * are shown first and run only once `confirm` says yes: they come from a shared file anyone on the team can edit.
+ */
+export async function checkTools({ approve: wantApprove = false, confirm = () => Promise.resolve(false), } = {}) {
+    const stack = resolveExpressions(readData('registry'));
+    if (!stack)
+        return { error: 'no stack loaded (koppler init)' };
+    const commands = stackCommands(stack);
+    const source = stack.source ?? '';
+    if (wantApprove) {
+        if (!commands.length)
+            console.log('This stack runs nothing of its own, so there is nothing to approve.');
+        else {
+            console.log(`The stack at ${source} would run or write these on this Mac. Anyone who can edit the stack wrote them:\n`);
+            for (const command of commands) {
+                const lines = command.run.split('\n').map(line => `    ${line}`);
+                console.log(`  ${command.what}: ${command.name}\n${lines.join('\n')}\n`);
+            }
+            if (!(await confirm('Allow all of these?')))
+                return { error: "not approved; the stack's own commands and code changes stay off" };
+            approve(source, stack);
+            console.log('Approved. They are allowed from now on, until any of them changes.\n');
+        }
+    }
+    const results = runChecks(stack);
+    save(stack, results);
+    return { results };
+}
+//# sourceMappingURL=checks.js.map