@brutalsystems/dray 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# dray
+
+Convention-driven multi-repo deploy orchestrator — "forge, but for shipping."
+
+`dray` builds/pushes container images to ECR, renders + applies k8s manifests
+(pinning a git SHA into image references), rolls out workloads, publishes Piral
+pilets, and syncs secrets — driven by a `.dray/config.json` committed in each
+repo. One entry point, interactive or scripted; no daemon.
+
+## Install
+
+```bash
+npm i -g @brutalsystems/dray
+```
+
+## Setup (per machine)
+
+1. Global defaults — `~/.dray/config.json`:
+   ```json
+   {
+     "defaults": {
+       "profile": "<aws-profile>", "region": "<region>", "account": "<acct-id>",
+       "platform": "linux/arm64", "context": "<kube-context>", "namespace": "<namespace>"
+     }
+   }
+   ```
+2. Register each repo: `dray add /path/to/repo` (reads its `.dray/config.json`;
+   registry is stored at `~/.dray/registry.json`).
+
+Requires `docker buildx`, `kubectl`, `git`, `aws`, and (for pilets/secrets) `sops`.
+
+## Commands
+
+```bash
+dray                        # interactive menu
+dray list                   # registered repos + targets
+dray ship <repo>:<target>   # deps?→build→push(SHA)→render+apply→rollout
+dray ship <repo>            # all enabled workloads in the repo
+dray apply  <repo>:<target> # render + apply manifests only
+dray rollout <repo>:<target>
+dray status <repo>          # running image SHA vs HEAD
+dray rollback <repo>:<target> <sha>
+dray publish <repo>[:<pilet>]   # publish pilet(s) via sops exec-env
+dray secrets sync <repo>
+```
+
+Global flags: `--dry-run` (print the plan, run nothing), `--allow-dirty`
+(build a dirty tree, tags `:<sha>-dirty`), `--all` (every registered repo).
+
+## `.dray/config.json` (per repo)
+
+```jsonc
+{
+  "name": "myrepo",
+  "images": [
+    { "name": "app", "ecr": "app", "source": { "local": true },
+      "dockerfile": "Dockerfile", "context": ".",
+      // optional: rebuild a cached deps layer when lockfiles change
+      "depsImage": { "dockerfile": "Dockerfile.deps", "tag": "app:deps", "rebuildOn": ["uv.lock"] },
+      // optional: inject --build-arg from an env file (e.g. VITE_* from .env.production)
+      "buildArgs": { "envFile": ".env.production", "prefix": "VITE_" } },
+    // image from another repo (cloned to a tmp dir, built, pushed):
+    { "name": "svc", "ecr": "svc", "source": { "git": "https://github.com/org/svc", "ref": "main" } }
+  ],
+  "workloads": [
+    // kind: deployment (rolled out) or cronjob (applied only)
+    { "name": "app", "kind": "deployment", "image": "app",
+      "manifests": [".k8s/deployment.yaml", ".k8s/service.yaml"], "stampImages": ["app"] },
+    // disabled: kept in config but skipped (e.g. served elsewhere)
+    { "name": "legacy", "kind": "deployment", "image": "app", "manifests": ["..."], "disabled": true },
+    // image-less: apply-only (third-party image lives literally in the manifest)
+    { "name": "searxng", "kind": "deployment", "manifests": [".k8s/searxng.yaml"] }
+  ],
+  "secrets": [
+    { "name": "app-secrets", "kind": "sops-manifest", "file": ".k8s/secrets.enc.yaml" }
+  ],
+  "pilets": {
+    "secretsFile": "secrets.env",
+    "command": ["npm", "run", "publish:feed", "--", "--pilet", "{name}"],
+    "names": ["foo", "bar"]
+  }
+}
+```
+
+### Image pinning
+
+Manifests reference managed images by a placeholder var — `${APP_IMAGE}`
+(derived `<UPPER_SNAKE(name)>_IMAGE`, or set `templateVar`). On apply, dray
+substitutes `<ecr>:<gitSHA>` for that var across the listed files (container
+image, env-var image refs, cronjob images — uniformly). A raw `kubectl apply`
+of an unrendered manifest fails loud, so applies always go through dray.

package/bin/dray.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli').run(process.argv).catch((e) => { console.error(e.message || e); process.exit(1); });

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@brutalsystems/dray",
+  "version": "0.1.0",
+  "description": "Convention-driven multi-repo deploy orchestrator (forge for shipping)",
+  "bin": { "dray": "bin/dray.js" },
+  "files": ["bin", "src", "README.md"],
+  "scripts": { "test": "node --test" },
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "license": "UNLICENSED",
+  "repository": { "type": "git", "url": "git+https://github.com/BrutalSystems/dray.git" },
+  "dependencies": { "commander": "^12.0.0" }
+}

package/src/cli/commands/add.js

@@ -0,0 +1,7 @@
+const { loadRepoConfig } = require('../../config/repo'); const { addRepo } = require('../../config/registry');
+module.exports = function registerAdd(program) {
+  program.command('add [repoPath]').description('Register a repo').action((repoPath) => {
+    const p = repoPath || process.cwd(); const config = loadRepoConfig(p);
+    addRepo(undefined, { name: config.name, path: p, config }); console.log(`registered ${config.name} → ${p}`);
+  });
+};

package/src/cli/commands/apply.js

@@ -0,0 +1,6 @@
+const { runAction } = require('../run-action');
+module.exports = function registerApply(program) {
+  program.command('apply [target]').description('Render + apply manifests')
+    .option('--all', 'every registered repo')
+    .action((target, opts, cmd) => runAction(target, 'apply', { ...cmd.optsWithGlobals(), all: opts.all }));
+};

package/src/cli/commands/build.js

@@ -0,0 +1,6 @@
+const { runAction } = require('../run-action');
+module.exports = function registerBuild(program) {
+  program.command('build [target]').description('Build image(s)')
+    .option('--all', 'every registered repo')
+    .action((target, opts, cmd) => runAction(target, 'build', { ...cmd.optsWithGlobals(), all: opts.all }));
+};

package/src/cli/commands/init.js

@@ -0,0 +1,14 @@
+const fs = require('node:fs'); const path = require('node:path');
+module.exports = function registerInit(program) {
+  program.command('init').description('Scaffold .dray/config.json').action(() => {
+    const dir = path.join(process.cwd(), '.dray'); fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'config.json'); if (fs.existsSync(file)) return console.log('.dray/config.json exists');
+    fs.writeFileSync(file, JSON.stringify({
+      name: path.basename(process.cwd()),
+      images: [{ name: 'app', ecr: 'app', source: { local: true }, dockerfile: 'Dockerfile', context: '.' }],
+      workloads: [{ name: 'app', kind: 'deployment', image: 'app', manifests: ['.k8s/deployment.yaml'] }],
+      secrets: [], pilets: [],
+    }, null, 2));
+    console.log(`wrote ${file}`);
+  });
+};

package/src/cli/commands/list.js

@@ -0,0 +1,9 @@
+const { allRepos } = require('../../config/registry');
+module.exports = function registerList(program) {
+  program.command('list').description('List repos + workloads').action(() => {
+    for (const [n, e] of Object.entries(allRepos())) {
+      const w = (e.config.workloads || []).map((x) => `${x.name}(${x.kind})`).join(', ') || '(none)';
+      console.log(`${n}  [${w}]  ${e.path}`);
+    }
+  });
+};

package/src/cli/commands/publish.js

@@ -0,0 +1,19 @@
+const { allRepos } = require('../../config/registry'); const { publish } = require('../../primitives/pilet');
+module.exports = function registerPublish(program) {
+  program.command('publish <target>').description('Publish pilet(s): "<repo>" for all, or "<repo>:<pilet>" for one')
+    .action(async (target, opts, cmd) => {
+      const dryRun = cmd.optsWithGlobals().dryRun;
+      const [repo, name] = target.split(':');
+      const entry = allRepos()[repo]; if (!entry) throw new Error(`unknown repo "${repo}"`);
+      const pilets = entry.config.pilets;
+      if (!pilets || !Array.isArray(pilets.names) || !pilets.names.length) {
+        throw new Error(`no pilets configured in ${repo}`);
+      }
+      const names = name ? [name] : pilets.names;
+      for (const n of names) {
+        if (!pilets.names.includes(n)) throw new Error(`unknown pilet "${n}" in ${repo}`);
+        const command = pilets.command.map((part) => part.split('{name}').join(n));
+        await publish({ repoPath: entry.path, secretsFile: pilets.secretsFile, publishCommand: command, dryRun });
+      }
+    });
+};

package/src/cli/commands/push.js

@@ -0,0 +1,6 @@
+const { runAction } = require('../run-action');
+module.exports = function registerPush(program) {
+  program.command('push [target]').description('Build + push image(s)')
+    .option('--all', 'every registered repo')
+    .action((target, opts, cmd) => runAction(target, 'push', { ...cmd.optsWithGlobals(), all: opts.all }));
+};

package/src/cli/commands/reload.js

@@ -0,0 +1,8 @@
+const { loadRepoConfig } = require('../../config/repo'); const { allRepos, addRepo } = require('../../config/registry');
+module.exports = function registerReload(program) {
+  program.command('reload [repo]').description('Re-read config').action((repo) => {
+    const reg = allRepos(); for (const n of (repo ? [repo] : Object.keys(reg))) {
+      addRepo(undefined, { name: n, path: reg[n].path, config: loadRepoConfig(reg[n].path) }); console.log(`reloaded ${n}`);
+    }
+  });
+};

package/src/cli/commands/remove.js

@@ -0,0 +1,4 @@
+const { removeRepo } = require('../../config/registry');
+module.exports = function registerRemove(program) {
+  program.command('remove <repo>').description('Unregister a repo').action((r) => { removeRepo(undefined, r); console.log(`removed ${r}`); });
+};

package/src/cli/commands/rollback.js

@@ -0,0 +1,15 @@
+const { loadGlobalConfig } = require('../../config/global'); const { allRepos } = require('../../config/registry');
+const { resolveTargets } = require('../../core/resolve'); const { renderManifests } = require('../../core/render'); const { applyFile } = require('../../primitives/kubectl');
+module.exports = function registerRollback(program) {
+  program.command('rollback <target> <sha>').description('Re-render + apply a prior SHA')
+    .action(async (target, sha, opts, cmd) => {
+      const dryRun = cmd.optsWithGlobals().dryRun; const { defaults } = loadGlobalConfig();
+      const units = resolveTargets({ registry: allRepos(), globalDefaults: defaults, spec: target }).filter((u) => u.manifests.length);
+      for (const u of units) {
+        const vars = {}; for (const s of u.stamp) vars[s.var] = `${s.repoUri}:${sha}`;
+        for (const f of renderManifests(u.manifests, vars, u.repoPath, { dryRun }))
+          await applyFile({ file: f, context: u.defaults.context, namespace: u.defaults.namespace, dryRun });
+        console.log(`rolled ${u.repo}:${u.workload || u.image.name} → ${sha}`);
+      }
+    });
+};

package/src/cli/commands/rollout.js

@@ -0,0 +1,6 @@
+const { runAction } = require('../run-action');
+module.exports = function registerRollout(program) {
+  program.command('rollout [target]').description('Restart + wait deployments')
+    .option('--all', 'every registered repo')
+    .action((target, opts, cmd) => runAction(target, 'rollout', { ...cmd.optsWithGlobals(), all: opts.all }));
+};

package/src/cli/commands/secrets.js

@@ -0,0 +1,14 @@
+const { loadGlobalConfig } = require('../../config/global'); const { allRepos } = require('../../config/registry');
+const { mergeDefaults } = require('../../core/resolve'); const { syncSecret } = require('../../primitives/secrets');
+module.exports = function registerSecrets(program) {
+  const grp = program.command('secrets').description('Secrets operations');
+  grp.command('sync <repo> [name]').description('Sync declared secrets')
+    .action(async (repo, name, opts, c) => {
+      const dryRun = c.optsWithGlobals().dryRun; const entry = allRepos()[repo]; if (!entry) throw new Error(`unknown repo "${repo}"`);
+      const { defaults } = loadGlobalConfig(); const d = mergeDefaults(defaults, entry.config, {});
+      for (const s of (entry.config.secrets || []).filter((s) => !name || s.name === name)) {
+        await syncSecret(s, { repoPath: entry.path, context: d.context, namespace: d.namespace, profile: d.profile, dryRun });
+        console.log(`synced ${s.name}`);
+      }
+    });
+};

package/src/cli/commands/ship.js

@@ -0,0 +1,6 @@
+const { runAction } = require('../run-action');
+module.exports = function registerShip(program) {
+  program.command('ship [target]').description('Build + push + apply + rollout a target')
+    .option('--all', 'every registered repo')
+    .action((target, opts, cmd) => runAction(target, 'ship', { ...cmd.optsWithGlobals(), all: opts.all }));
+};

package/src/cli/commands/status.js

@@ -0,0 +1,15 @@
+const { loadGlobalConfig } = require('../../config/global'); const { allRepos } = require('../../config/registry');
+const { resolveTargets } = require('../../core/resolve'); const { runningImage } = require('../../primitives/kubectl'); const { currentSha } = require('../../primitives/git');
+module.exports = function registerStatus(program) {
+  program.command('status [target]').description('Running image SHA vs HEAD').option('--all', 'all repos')
+    .action(async (target, opts) => {
+      const { defaults } = loadGlobalConfig();
+      const units = resolveTargets({ registry: allRepos(), globalDefaults: defaults, spec: opts.all || !target ? '--all' : target }).filter((u) => u.workload);
+      for (const u of units) {
+        const live = await runningImage({ workload: u.workload, kind: u.kind, context: u.defaults.context, namespace: u.defaults.namespace });
+        const head = await currentSha(u.repoPath).catch(() => '?');
+        const tag = live.includes(':') ? live.split(':').pop() : '(none)';
+        console.log(`${u.repo}:${u.workload}  running ${tag}  ${tag === head ? 'up-to-date' : `behind (HEAD ${head})`}`);
+      }
+    });
+};

package/src/cli/commands/version.js

@@ -0,0 +1,4 @@
+const { version } = require('../../../package.json');
+module.exports = function registerVersion(program) {
+  program.command('version').description('Show dray version').action(() => console.log(`dray ${version}`));
+};

package/src/cli/index.js

@@ -0,0 +1,14 @@
+const { Command } = require('commander');
+async function run(argv) {
+  if (argv.length <= 2) { await require('./menu').menu(); return; }
+  const program = new Command();
+  program.name('dray').description('Convention-driven multi-repo deploy orchestrator');
+  program.option('--dry-run', 'print planned commands, run nothing');
+  program.option('--allow-dirty', 'allow building from a dirty tree (tags :<sha>-dirty)');
+  for (const c of ['version', 'init', 'add', 'remove', 'reload', 'list',
+    'build', 'push', 'apply', 'rollout', 'ship', 'status', 'rollback', 'publish', 'secrets']) {
+    require(`./commands/${c}`)(program);
+  }
+  await program.parseAsync(argv);
+}
+module.exports = { run };

package/src/cli/menu.js

@@ -0,0 +1,20 @@
+const readline = require('node:readline'); const { allRepos } = require('../config/registry'); const { runAction } = require('./run-action');
+function buildMenuTree(registry) {
+  return {
+    repos: Object.entries(registry).map(([name, e]) => ({ name, targets: (e.config.workloads || []).map((w) => ({ label: w.name, spec: `${name}:${w.name}` })) })),
+    actions: ['ship', 'build', 'apply', 'rollout', 'status'],
+  };
+}
+function defaultIo() { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); return { question: (q) => new Promise((r) => rl.question(q, r)), close: () => rl.close() }; }
+async function menu(io = defaultIo()) {
+  const t = buildMenuTree(allRepos());
+  t.repos.forEach((r, i) => console.log(`${i + 1}) ${r.name}`));
+  const repo = t.repos[parseInt(await io.question('repo #: '), 10) - 1]; if (!repo) return io.close();
+  repo.targets.forEach((x, i) => console.log(`${i + 1}) ${x.label}`));
+  const target = repo.targets[parseInt(await io.question('target #: '), 10) - 1];
+  t.actions.forEach((a, i) => console.log(`${i + 1}) ${a}`));
+  const action = t.actions[parseInt(await io.question('action #: '), 10) - 1];
+  const ok = (await io.question(`${action} ${target.spec}? [y/N] `)).trim().toLowerCase() === 'y';
+  io.close(); if (ok) await runAction(target.spec, action, { dryRun: false });
+}
+module.exports = { buildMenuTree, menu };

package/src/cli/run-action.js

@@ -0,0 +1,9 @@
+const { loadGlobalConfig } = require('../config/global'); const { allRepos } = require('../config/registry');
+const { resolveTargets } = require('../core/resolve'); const { planFor } = require('../core/plan'); const { execute } = require('../core/engine');
+async function runAction(target, action, { dryRun, allowDirty, all }) {
+  const registry = allRepos(); const { defaults } = loadGlobalConfig();
+  const spec = all ? '--all' : target;
+  const units = resolveTargets({ registry, globalDefaults: defaults, spec });
+  await execute(planFor(units, action), { dryRun, allowDirty });
+}
+module.exports = { runAction };

package/src/config/global.js

@@ -0,0 +1,4 @@
+const fs = require('node:fs'); const { GLOBAL_CONFIG } = require('../constants');
+function parseGlobalConfig(raw) { if (!raw) return { defaults: {} }; const o = JSON.parse(raw); return { defaults: o.defaults || {} }; }
+function loadGlobalConfig() { return parseGlobalConfig(fs.existsSync(GLOBAL_CONFIG) ? fs.readFileSync(GLOBAL_CONFIG, 'utf8') : null); }
+module.exports = { parseGlobalConfig, loadGlobalConfig };

package/src/config/registry.js

@@ -0,0 +1,8 @@
+const fs = require('node:fs'); const path = require('node:path'); const { REGISTRY } = require('../constants');
+function loadRegistry(file = REGISTRY) { return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {}; }
+function saveRegistry(file = REGISTRY, reg = {}) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(reg, null, 2)); }
+function addRepo(file, { name, path: p, config }) { const r = loadRegistry(file); r[name] = { path: p, config, addedAt: new Date().toISOString() }; saveRegistry(file, r); return r[name]; }
+function getRepo(file, name) { return loadRegistry(file)[name]; }
+function removeRepo(file, name) { const r = loadRegistry(file); delete r[name]; saveRegistry(file, r); }
+function allRepos(file) { return loadRegistry(file); }
+module.exports = { loadRegistry, saveRegistry, addRepo, getRepo, removeRepo, allRepos };

package/src/config/repo.js

@@ -0,0 +1,32 @@
+const fs = require('node:fs'); const path = require('node:path');
+const WORKLOAD_KINDS = new Set(['deployment', 'cronjob']);
+const SECRET_KINDS = new Set(['sops-manifest', 'literal-from-env', 'sops-exec-env']);
+function loadRepoConfig(repoPath) {
+  const file = path.join(repoPath, '.dray', 'config.json');
+  if (!fs.existsSync(file)) throw new Error(`no .dray/config.json in ${repoPath}`);
+  return validateRepoConfig(JSON.parse(fs.readFileSync(file, 'utf8')));
+}
+function validateRepoConfig(cfg) {
+  const e = [];
+  if (!cfg.name || typeof cfg.name !== 'string') e.push('name must be a non-empty string');
+  const imageNames = new Set();
+  for (const img of cfg.images || []) {
+    if (!img.name) e.push('image missing name');
+    if (!img.ecr) e.push(`image "${img.name}" missing ecr`);
+    if (!(img.source && (img.source.local || img.source.git))) e.push(`image "${img.name}" needs source.local or source.git`);
+    imageNames.add(img.name);
+  }
+  for (const w of cfg.workloads || []) {
+    if (!w.name) e.push('workload missing name');
+    if (!WORKLOAD_KINDS.has(w.kind)) e.push(`workload "${w.name}" kind must be deployment|cronjob`);
+    if (w.image !== undefined && !imageNames.has(w.image)) e.push(`workload "${w.name}" references unknown image "${w.image}"`);
+    if (!Array.isArray(w.manifests) || w.manifests.length === 0) e.push(`workload "${w.name}" needs a non-empty manifests list`);
+  }
+  for (const s of cfg.secrets || []) {
+    if (!s.name) e.push('secret missing name');
+    if (!SECRET_KINDS.has(s.kind)) e.push(`secret "${s.name}" kind must be sops-manifest|literal-from-env|sops-exec-env`);
+  }
+  if (e.length) throw new Error(`invalid .dray/config.json:\n  - ${e.join('\n  - ')}`);
+  return cfg;
+}
+module.exports = { loadRepoConfig, validateRepoConfig };

package/src/constants.js

@@ -0,0 +1,3 @@
+const os = require('node:os'); const path = require('node:path');
+const DRAY_HOME = path.join(os.homedir(), '.dray');
+module.exports = { DRAY_HOME, GLOBAL_CONFIG: path.join(DRAY_HOME, 'config.json'), REGISTRY: path.join(DRAY_HOME, 'registry.json') };

package/src/core/buildArgs.js

@@ -0,0 +1,34 @@
+const fs = require('node:fs'); const path = require('node:path');
+
+function stripQuotes(v) {
+  const t = v.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+// Returns ["KEY=VALUE", ...] for `docker build --build-arg`. An image may set
+// `buildArgs: { envFile, prefix }` to inject vars from an env file (e.g. VITE_*
+// from .env.production), and/or `buildArgs.values: { K: V }` for explicit pairs.
+function resolveBuildArgs(image, cwd) {
+  const cfg = image && image.buildArgs;
+  if (!cfg) return [];
+  const out = [];
+  if (cfg.envFile) {
+    const p = path.join(cwd, cfg.envFile);
+    if (fs.existsSync(p)) {
+      for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+        if (!m) continue;
+        const [, k, v] = m;
+        if (cfg.prefix && !k.startsWith(cfg.prefix)) continue;
+        out.push(`${k}=${stripQuotes(v)}`);
+      }
+    }
+  }
+  for (const [k, v] of Object.entries(cfg.values || {})) out.push(`${k}=${v}`);
+  return out;
+}
+
+module.exports = { resolveBuildArgs };

package/src/core/depsCache.js

@@ -0,0 +1,17 @@
+const fs = require('node:fs'); const path = require('node:path'); const crypto = require('node:crypto');
+const { DRAY_HOME } = require('../constants');
+function needsDepsRebuild(image, repoPath, repo, stateDir = path.join(DRAY_HOME, 'depshash')) {
+  if (!image.depsImage) return false;
+  const h = crypto.createHash('sha256');
+  for (const rel of image.depsImage.rebuildOn || []) {
+    const p = path.join(repoPath, rel); h.update(rel);
+    h.update(fs.existsSync(p) ? fs.readFileSync(p) : Buffer.from('MISSING'));
+  }
+  const digest = h.digest('hex');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const file = path.join(stateDir, `${repo}__${image.name}.depshash`);
+  const prev = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+  if (prev === digest) return false;
+  fs.writeFileSync(file, digest); return true;
+}
+module.exports = { needsDepsRebuild };

package/src/core/engine.js

@@ -0,0 +1,61 @@
+const fs = require('node:fs'); const path = require('node:path');
+const real = {
+  docker: require('../primitives/docker'), kubectl: require('../primitives/kubectl'),
+  git: require('../primitives/git'), secrets: require('../primitives/secrets'),
+  render: require('./render'), depsCache: require('./depsCache'),
+  buildArgs: require('./buildArgs'),
+};
+async function shaForUnit(u, d, cache, dryRun, allowDirty) {
+  if (!u.image) return null; // apply-only workload: no image, no sha/build
+  const key = `${u.repo}/${u.image.name}`;
+  if (cache.has(key)) return cache.get(key);
+  let sha;
+  if (u.image.source && u.image.source.git) {
+    if (dryRun) sha = 'DRYRUN';
+    else { const c = await d.git.cloneToTmp(u.image.source); u._clone = c; sha = c.sha; }
+  } else if (dryRun) {
+    sha = 'DRYRUN';
+  } else {
+    const dirty = await d.git.isDirty(u.repoPath);
+    if (dirty && !allowDirty) throw new Error(`working tree is dirty in ${u.repoPath} (commit, or pass --allow-dirty)`);
+    sha = await d.git.currentSha(u.repoPath);
+    if (dirty) sha = `${sha}-dirty`;
+  }
+  cache.set(key, sha);
+  return sha;
+}
+async function execute(steps, { dryRun = false, allowDirty = false, deps } = {}) {
+  const d = { ...real, ...deps };
+  const shaCache = new Map(); const clones = []; const renderDirs = [];
+  let loggedIn = false;
+  try {
+    for (const step of steps) {
+      const u = step.unit;
+      if (step.kind === 'secret') {
+        await d.secrets.syncSecret(step.secret, { repoPath: u.repoPath, context: u.defaults.context, namespace: u.defaults.namespace, profile: u.defaults.profile, dryRun });
+        continue;
+      }
+      const sha = await shaForUnit(u, d, shaCache, dryRun, allowDirty);
+      if (u._clone && !clones.includes(u._clone)) clones.push(u._clone);
+      const cwd = u._clone ? u._clone.dir : u.repoPath;
+      if (step.kind === 'deps') { if (d.depsCache.needsDepsRebuild(u.image, cwd, u.repo)) await d.docker.buildDeps(u.image, cwd, dryRun); }
+      else if (step.kind === 'build') await d.docker.buildImage({ ecrUri: u.repoUri, sha, dockerfile: u.image.dockerfile, context: u.image.context || '.', platform: u.defaults.platform, cwd, dryRun, buildArgs: d.buildArgs.resolveBuildArgs(u.image, cwd) });
+      else if (step.kind === 'push') {
+        if (!loggedIn) { await d.docker.ecrLogin({ account: u.defaults.account, region: u.defaults.region, profile: u.defaults.profile, dryRun }); await d.docker.ensureRepo({ ecr: u.image.ecr, account: u.defaults.account, region: u.defaults.region, profile: u.defaults.profile, dryRun }); loggedIn = true; }
+        await d.docker.pushImage({ ecrUri: u.repoUri, sha, dryRun });
+      } else if (step.kind === 'apply') {
+        const vars = {}; for (const s of u.stamp) vars[s.var] = `${s.repoUri}:${sha}`;
+        const files = d.render.renderManifests(u.manifests, vars, u.repoPath, { dryRun });
+        if (files[0]) renderDirs.push(path.dirname(files[0]));
+        for (const f of files) await d.kubectl.applyFile({ file: f, context: u.defaults.context, namespace: u.defaults.namespace, dryRun });
+      } else if (step.kind === 'rollout') {
+        try { await d.kubectl.rollout({ deployment: u.workload, context: u.defaults.context, namespace: u.defaults.namespace, dryRun }); }
+        catch (err) { await d.kubectl.rolloutUndo({ deployment: u.workload, context: u.defaults.context, namespace: u.defaults.namespace, dryRun }); throw err; }
+      }
+    }
+  } finally {
+    for (const c of clones) c.cleanup();
+    for (const dir of renderDirs) fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+module.exports = { execute };

package/src/core/plan.js

@@ -0,0 +1,65 @@
+function uniqueImages(units) {
+  const seen = new Map();
+  for (const u of units) {
+    if (!u.image) continue; // apply-only workload (no image to build/push)
+    const key = `${u.repo}/${u.image.name}`;
+    if (!seen.has(key)) seen.set(key, u);
+  }
+  return [...seen.values()];
+}
+const buildSteps = (u) => {
+  const s = [];
+  if (u.image.depsImage) s.push({ kind: 'deps', label: `deps ${u.image.name}`, unit: u });
+  s.push({ kind: 'build', label: `build ${u.image.name}`, unit: u });
+  return s;
+};
+const withManifests = (units) => units.filter((u) => u.manifests && u.manifests.length);
+const deployments = (units) => units.filter((u) => u.kind === 'deployment');
+function topoSort(units) {
+  const byName = new Map(units.map((u) => [u.workload, u]));
+  const out = []; const seen = new Set();
+  const visit = (u) => {
+    if (!u || seen.has(u.workload)) return; seen.add(u.workload);
+    for (const dep of u.dependsOn || []) if (!dep.startsWith('secret:')) visit(byName.get(dep));
+    out.push(u);
+  };
+  for (const u of units) visit(u);
+  return out;
+}
+function secretSteps(units) {
+  // Repo-scoped dedup (a secret named "mongodb-app" in two repos is two
+  // distinct steps). Each step carries the fully-resolved secret object from
+  // its OWNING unit — no fragile name lookup / silent fallback in the engine.
+  const out = []; const seen = new Set();
+  for (const u of units) {
+    for (const d of u.dependsOn || []) {
+      if (!d.startsWith('secret:')) continue;
+      const name = d.slice('secret:'.length);
+      const key = `${u.repo}/${name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const secret = (u._secrets || []).find((s) => s.name === name);
+      if (!secret) throw new Error(`${u.repo}: workload "${u.workload}" dependsOn secret "${name}" not declared in secrets[]`);
+      out.push({ kind: 'secret', label: `secret ${u.repo}:${name}`, secret, unit: u });
+    }
+  }
+  return out;
+}
+function planFor(units, action) {
+  const imgs = uniqueImages(units);
+  if (action === 'build') return imgs.flatMap(buildSteps);
+  if (action === 'push') return imgs.flatMap((u) => [...buildSteps(u), { kind: 'push', label: `push ${u.image.name}`, unit: u }]);
+  if (action === 'apply') return withManifests(units).map((u) => ({ kind: 'apply', label: `apply ${u.workload || u.image.name}`, unit: u }));
+  if (action === 'rollout') return deployments(units).map((u) => ({ kind: 'rollout', label: `rollout ${u.workload}`, unit: u }));
+  if (action === 'ship') {
+    const ordered = topoSort(units);
+    return [
+      ...imgs.flatMap((u) => [...buildSteps(u), { kind: 'push', label: `push ${u.image.name}`, unit: u }]),
+      ...secretSteps(ordered),
+      ...withManifests(ordered).map((u) => ({ kind: 'apply', label: `apply ${u.workload || u.image.name}`, unit: u })),
+      ...deployments(ordered).map((u) => ({ kind: 'rollout', label: `rollout ${u.workload}`, unit: u })),
+    ];
+  }
+  throw new Error(`unknown action "${action}"`);
+}
+module.exports = { planFor };

package/src/core/render.js

@@ -0,0 +1,17 @@
+const fs = require('node:fs'); const os = require('node:os'); const path = require('node:path');
+function renderString(text, vars) {
+  let out = text;
+  for (const [k, v] of Object.entries(vars)) out = out.split(`\${${k}}`).join(v);
+  return out;
+}
+function renderManifests(files, vars, cwd, { dryRun } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dray-render-'));
+  return files.map((rel) => {
+    const src = path.join(cwd, rel);
+    const rendered = renderString(fs.readFileSync(src, 'utf8'), vars);
+    const out = path.join(dir, rel.replace(/[/\\]/g, '__'));
+    fs.writeFileSync(out, rendered);
+    return out;
+  });
+}
+module.exports = { renderString, renderManifests };

package/src/core/resolve.js

@@ -0,0 +1,59 @@
+const KEYS = ['profile', 'region', 'account', 'platform', 'context', 'namespace'];
+const upperSnake = (s) => s.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase();
+function imageVar(image) { return image.templateVar || `${upperSnake(image.name)}_IMAGE`; }
+function mergeDefaults(globalDefaults = {}, repoCfg = {}, entry = {}) {
+  const repo = repoCfg.defaults || {}; const out = {};
+  for (const k of KEYS) out[k] = entry[k] ?? repo[k] ?? globalDefaults[k];
+  return out;
+}
+function ecrRepoUri(defaults, image) { return `${defaults.account}.dkr.ecr.${defaults.region}.amazonaws.com/${image.ecr}`; }
+
+function unitsForRepo(name, entry, globalDefaults, filter) {
+  const cfg = entry.config;
+  const images = new Map((cfg.images || []).map((i) => [i.name, i]));
+  const workloads = cfg.workloads || [];
+  const units = [];
+  const mk = (image, w) => {
+    const defaults = mergeDefaults(globalDefaults, cfg, w || {});
+    // A workload may have no image (apply-only, e.g. a third-party image that
+    // lives literally in the manifest) — then there's nothing to build or stamp.
+    const stampNames = (w && w.stampImages) || (image ? [image.name] : []);
+    const stamp = stampNames.map((n) => ({ var: imageVar(images.get(n)), repoUri: ecrRepoUri(defaults, images.get(n)) }));
+    units.push({
+      repo: name, repoPath: entry.path, image: image || null,
+      workload: w ? w.name : null, kind: w ? w.kind : null,
+      manifests: w ? w.manifests : [], dependsOn: (w && w.dependsOn) || [],
+      defaults, repoUri: image ? ecrRepoUri(defaults, image) : null, stamp,
+      _secrets: cfg.secrets || [],
+    });
+  };
+  const want = (w) => !filter || w.name === filter || w.image === filter;
+  for (const w of workloads) {
+    if (!want(w)) continue;
+    if (w.disabled) {
+      // Documented in config but not deployed by dray (e.g. endpoints served
+      // elsewhere). Skip in bare-repo/--all; error if explicitly targeted by name.
+      if (filter && w.name === filter) {
+        throw new Error(`workload "${w.name}" is disabled in ${name}'s .dray/config.json`);
+      }
+      continue;
+    }
+    mk(images.get(w.image), w);
+  }
+  for (const img of images.values()) {
+    const matches = !filter || img.name === filter;
+    const hasWorkload = workloads.some((w) => w.image === img.name);
+    if (matches && !hasWorkload) mk(img, null);
+  }
+  return units;
+}
+function resolveTargets({ registry, globalDefaults, spec }) {
+  if (spec === '--all') return Object.entries(registry).flatMap(([n, e]) => unitsForRepo(n, e, globalDefaults, null));
+  const [repo, name] = spec.split(':');
+  const entry = registry[repo];
+  if (!entry) throw new Error(`unknown repo "${repo}" (run: dray add)`);
+  const units = unitsForRepo(repo, entry, globalDefaults, name || null);
+  if (!units.length) throw new Error(`no target "${spec}" found`);
+  return units;
+}
+module.exports = { mergeDefaults, imageVar, ecrRepoUri, resolveTargets };

package/src/primitives/docker.js

@@ -0,0 +1,22 @@
+let _run = require('./exec').run; function _withRun(fn) { _run = fn; }
+function buildImage({ ecrUri, sha, dockerfile, context, platform, cwd, dryRun, buildArgs = [] }) {
+  const args = ['buildx', 'build', '--platform', platform, '-f', dockerfile, '-t', `${ecrUri}:${sha}`];
+  for (const a of buildArgs) args.push('--build-arg', a);
+  args.push('--load', context);
+  return _run('docker', args, { cwd, dryRun });
+}
+function pushImage({ ecrUri, sha, dryRun }) { return _run('docker', ['push', `${ecrUri}:${sha}`], { dryRun }); }
+function buildDeps(image, cwd, dryRun) {
+  const d = image.depsImage;
+  return _run('docker', ['buildx', 'build', '--platform', 'linux/arm64', '-f', d.dockerfile, '-t', d.tag, '--load', '.'], { cwd, dryRun });
+}
+function ecrLogin({ account, region, profile, dryRun }) {
+  const reg = `${account}.dkr.ecr.${region}.amazonaws.com`; const prof = profile ? `--profile ${profile} ` : '';
+  return _run('bash', ['-c', `aws ecr get-login-password --region ${region} ${prof}| docker login --username AWS --password-stdin ${reg}`], { dryRun });
+}
+async function ensureRepo({ ecr, account, region, profile, dryRun }) {
+  const prof = profile ? ['--profile', profile] : [];
+  const r = await _run('aws', ['ecr', 'describe-repositories', '--repository-names', ecr, '--region', region, ...prof], { capture: true, allowFail: true, dryRun });
+  if (r.code !== 0) await _run('aws', ['ecr', 'create-repository', '--repository-name', ecr, '--region', region, ...prof], { dryRun });
+}
+module.exports = { buildImage, pushImage, buildDeps, ecrLogin, ensureRepo, _withRun };

package/src/primitives/exec.js

@@ -0,0 +1,18 @@
+const { spawn } = require('node:child_process');
+function run(cmd, args = [], opts = {}) {
+  if (opts.dryRun) {
+    console.log(`▶ ${cmd} ${args.join(' ')}${opts.cwd ? ` (cwd: ${opts.cwd})` : ''}`);
+    return Promise.resolve({ code: 0, stdout: '', stderr: '' });
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd: opts.cwd, stdio: opts.capture ? ['inherit', 'pipe', 'pipe'] : 'inherit' });
+    let stdout = '', stderr = '';
+    if (opts.capture) { child.stdout.on('data', (d) => { stdout += d; }); child.stderr.on('data', (d) => { stderr += d; }); }
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0 && !opts.allowFail) reject(new Error(`${cmd} ${args.join(' ')} failed (exit ${code})\n${stderr}`));
+      else resolve({ code, stdout, stderr });
+    });
+  });
+}
+module.exports = { run };

package/src/primitives/git.js

@@ -0,0 +1,16 @@
+const fs = require('node:fs'); const os = require('node:os'); const path = require('node:path');
+const { run } = require('./exec');
+async function currentSha(cwd) { const { stdout } = await run('git', ['rev-parse', '--short', 'HEAD'], { cwd, capture: true }); return stdout.trim(); }
+async function isDirty(cwd) { const { stdout } = await run('git', ['status', '--porcelain'], { cwd, capture: true }); return stdout.trim().length > 0; }
+async function cloneToTmp({ git, ref }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dray-clone-'));
+  // Works for branch/tag refs always; arbitrary commit SHAs require the remote
+  // to allow SHA fetches (uploadpack.allowAnySHA1InWant).
+  await run('git', ['init', '-q', dir], { capture: true });
+  await run('git', ['-C', dir, 'remote', 'add', 'origin', git], { capture: true });
+  await run('git', ['-C', dir, 'fetch', '--depth', '1', 'origin', ref], { capture: true });
+  await run('git', ['-C', dir, 'checkout', '-q', 'FETCH_HEAD'], { capture: true });
+  const sha = await currentSha(dir);
+  return { dir, sha, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+module.exports = { currentSha, isDirty, cloneToTmp };

package/src/primitives/kubectl.js

@@ -0,0 +1,16 @@
+let _run = require('./exec').run; function _withRun(fn) { _run = fn; }
+const ns = (c, n) => ['-n', n, '--context', c];
+function applyFile({ file, context, namespace, dryRun }) { return _run('kubectl', ['apply', '-f', file, ...ns(context, namespace)], { dryRun }); }
+async function rollout({ deployment, context, namespace, dryRun }) {
+  await _run('kubectl', ['rollout', 'restart', `deployment/${deployment}`, ...ns(context, namespace)], { dryRun });
+  return _run('kubectl', ['rollout', 'status', `deployment/${deployment}`, '--timeout=180s', ...ns(context, namespace)], { dryRun });
+}
+function rolloutUndo({ deployment, context, namespace, dryRun }) { return _run('kubectl', ['rollout', 'undo', `deployment/${deployment}`, ...ns(context, namespace)], { dryRun }); }
+async function runningImage({ workload, kind, context, namespace }) {
+  const kindPath = kind === 'cronjob'
+    ? ['cronjob/' + workload, '-o', 'jsonpath={.spec.jobTemplate.spec.template.spec.containers[0].image}']
+    : ['deployment/' + workload, '-o', 'jsonpath={.spec.template.spec.containers[0].image}'];
+  const { stdout } = await _run('kubectl', ['get', ...kindPath, ...ns(context, namespace)], { capture: true, allowFail: true });
+  return stdout.trim();
+}
+module.exports = { applyFile, rollout, rolloutUndo, runningImage, _withRun };

package/src/primitives/pilet.js

@@ -0,0 +1,3 @@
+const sops = require('./sops');
+function publish({ repoPath, secretsFile, publishCommand, dryRun }) { return sops.execEnv(secretsFile, publishCommand, { cwd: repoPath, dryRun }); }
+module.exports = { publish };

package/src/primitives/secrets.js

@@ -0,0 +1,16 @@
+let _run = require('./exec').run; function _withRun(fn) { _run = fn; }
+async function syncSecret(secret, { repoPath, context, namespace, profile, dryRun }) {
+  if (secret.kind === 'sops-exec-env') return; // handled by pilet publish
+  if (secret.kind === 'sops-manifest') {
+    return _run('bash', ['-c', `sops -d ${secret.file} | kubectl apply -f - -n ${namespace} --context ${context}`], { cwd: repoPath, dryRun });
+  }
+  if (secret.kind === 'literal-from-env') {
+    await _run('bash', ['-c',
+      `kubectl create secret generic ${secret.name} --from-env-file=${secret.file} --dry-run=client -o yaml -n ${namespace} --context ${context} | kubectl apply -f - -n ${namespace} --context ${context}`],
+      { cwd: repoPath, dryRun });
+    for (const [k, v] of Object.entries(secret.reflector || {})) {
+      await _run('kubectl', ['annotate', 'secret', secret.name, `${k}=${v}`, '--overwrite', '-n', namespace, '--context', context], { dryRun });
+    }
+  }
+}
+module.exports = { syncSecret, _withRun };

package/src/primitives/sops.js

@@ -0,0 +1,12 @@
+let _run = require('./exec').run; function _withRun(fn) { _run = fn; }
+
+// sops `exec-env` takes the command as a SINGLE string (run via the shell),
+// not as `-- <argv>` (that form breaks on sops 3.x: "missing file to decrypt").
+// Join + shell-quote so args like `typer[all]` survive.
+function shQuote(a) {
+  return /^[A-Za-z0-9_\-.,:=/@]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`;
+}
+function execEnv(file, command, opts = {}) {
+  return _run('sops', ['exec-env', file, command.map(shQuote).join(' ')], opts);
+}
+module.exports = { execEnv, _withRun };