@esuyo/coding-container 1.0.2

package/src/commands/gc.js

@@ -0,0 +1,160 @@
+import { exec } from "../utils/exec.js";
+import { listTags, deleteTag } from "../utils/registry-api.js";
+import { allTagsSortAsc, isSemver, semverSortAsc } from "../utils/semver.js";
+import { kubectlExec } from "../utils/system-config.js";
+
+/**
+ * The tag part of a full image reference; "latest" when untagged.
+ */
+export function imageTag(image) {
+  const lastSlash = image.lastIndexOf("/");
+  const lastColon = image.lastIndexOf(":");
+  if (lastColon > lastSlash) return image.slice(lastColon + 1);
+  return "latest";
+}
+
+/**
+ * Retention plan for one repo (global or coding-<project>):
+ *   keep = {pinned, previous (global repos only), all in-use tags,
+ *           the `keep` semver predecessors of pinned (closest first)}
+ *   toDelete = everything else, oldest first.
+ * Non-semver tags (legacy timestamp tags) are never counted in the keep
+ * window — they are deletable unless in use (or literally pinned).
+ * In-use tags are never deleted, even more than `keep` behind pinned.
+ */
+export function planGc({ tags, inUse, pinned, previous, keep }) {
+  const sortedSemver = semverSortAsc(tags);
+  const keepSet = new Set();
+  if (pinned) keepSet.add(pinned);
+  if (previous) keepSet.add(previous);
+  for (const t of inUse) keepSet.add(t);
+  if (pinned && isSemver(pinned)) {
+    const idx = sortedSemver.indexOf(pinned);
+    if (idx > 0) {
+      for (const t of sortedSemver.slice(Math.max(0, idx - keep), idx)) keepSet.add(t);
+    }
+  }
+  const toDelete = [
+    ...sortedSemver.filter((t) => !keepSet.has(t)),
+    ...[...tags].filter((t) => !isSemver(t) && !keepSet.has(t)).sort(),
+  ];
+  const kept = allTagsSortAsc([...tags].filter((t) => keepSet.has(t)));
+  const nonSemver = [...tags].filter((t) => !isSemver(t)).sort();
+  return { toDelete, kept, nonSemver };
+}
+
+/**
+ * Tags referenced by coding-container deployments in the namespace — the
+ * images the cluster currently runs, which must never be deleted.
+ */
+function inUseTags(cfg) {
+  const { cmd, args, opts } = kubectlExec();
+  let out;
+  try {
+    out = exec(cmd, [
+      ...args,
+      "get", "deploy", "-n", cfg.k8s.namespace,
+      "-l", "coding-container=true", "-o", "json",
+    ], opts);
+  } catch (err) {
+    throw new Error(
+      `cannot list deployments in namespace ${cfg.k8s.namespace} to determine which ` +
+        `image tags are in use:\n${err.message}\n` +
+        `Refusing to delete tags without knowing which images are deployed.`
+    );
+  }
+  const tags = new Set();
+  for (const d of JSON.parse(out).items || []) {
+    const pod = d.spec?.template?.spec || {};
+    for (const c of [...(pod.containers || []), ...(pod.initContainers || [])]) {
+      if (c.image) tags.add(imageTag(c.image));
+    }
+  }
+  return tags;
+}
+
+/**
+ * List tags of cfg's repo, planning and (unless dryRun) deleting the
+ * unreferenced ones per planGc(). Shared by bare `gc` (custom repo) and
+ * `system gc` (global repo).
+ */
+export async function gcTags(cfg, { pinned, previous, keep, dryRun }) {
+  console.log(`Listing tags of ${cfg.image.registry}/${cfg.image.name} ...`);
+  let tags;
+  try {
+    tags = await listTags(cfg);
+  } catch (err) {
+    if (/was not found/i.test(err.message)) {
+      console.log("No tags found; nothing to do.");
+      return;
+    }
+    throw err;
+  }
+  if (tags.length === 0) {
+    console.log("No tags found; nothing to do.");
+    return;
+  }
+
+  const inUse = inUseTags(cfg);
+  const { toDelete, kept, nonSemver } = planGc({ tags, inUse, pinned, previous, keep });
+  console.log(
+    `Found ${tags.length} tag(s); in use: ${[...inUse].join(", ") || "none"}; ` +
+      `keeping ${kept.length}, ` +
+      (dryRun ? "would delete" : "deleting") + ` ${toDelete.length}.`
+  );
+  if (nonSemver.length) {
+    console.log(
+      `Note: ${nonSemver.length} non-semver tag(s) (${nonSemver.join(", ")}) are not ` +
+        `counted in the keep window (legacy tags); they are deleted unless in use.`
+    );
+  }
+
+  if (toDelete.length === 0) {
+    console.log("Nothing to delete.");
+    return;
+  }
+  if (dryRun) {
+    for (const t of toDelete) console.log(`  would delete ${t}`);
+    console.log("(dry run — nothing was deleted)");
+    return;
+  }
+
+  const failed = [];
+  for (const t of toDelete) {
+    try {
+      await deleteTag(cfg, t);
+      console.log(`Deleted ${t}`);
+    } catch (err) {
+      failed.push(t);
+      console.error(`Failed to delete ${t}: ${err.message}`);
+    }
+  }
+  if (failed.length) {
+    throw new Error(`could not delete ${failed.length} tag(s): ${failed.join(", ")}`);
+  }
+  console.log(
+    `Deleted ${toDelete.length} tag(s). Disk space is reclaimed when the registry ` +
+      `runs its own garbage collection (automatic on GitLab/Harbor; ` +
+      `"registry garbage-collect" on a bare Docker registry).`
+  );
+}
+
+/**
+ * Bare `gc`: garbage-collects the current project's custom repo
+ * (registry/coding-<project>). Global-mode projects have no custom repo —
+ * the shared image is pruned by `system gc` instead.
+ */
+export async function gc(cfg, { keep = 5, dryRun = false } = {}) {
+  if (cfg.imageMode === "global") {
+    throw new Error(
+      "this project uses the shared global image — there is no project repo to prune. " +
+        "Use 'coding-container system gc' to garbage-collect the global image."
+    );
+  }
+  if (!cfg.image.tag) {
+    throw new Error(
+      "custom image mode requires a tag: set image.tag in the project config or pass --tag"
+    );
+  }
+  await gcTags(cfg, { pinned: cfg.image.tag, previous: undefined, keep, dryRun });
+}

package/src/commands/push.js

@@ -0,0 +1,36 @@
+import { dockerExec, run } from "../utils/exec.js";
+import { imageRef } from "../config.js";
+
+/**
+ * The raw docker push of cfg's image (cfg.image.tag must be set). Used by
+ * custom-mode projects and by `system create` (the only writer of the
+ * global image).
+ */
+export async function pushImage(cfg) {
+  const ref = imageRef(cfg);
+  console.log(`Pushing ${ref} to ${cfg.image.registry} ...`);
+  const { cmd, opts } = dockerExec();
+  try {
+    await run(cmd, ["push", ref], opts);
+  } catch (err) {
+    throw new Error(
+      `Push failed for ${ref}. Make sure you are logged in to ${cfg.image.registry} (docker login ${cfg.image.registry}).\n${err.message}`
+    );
+  }
+  console.log(`Pushed ${ref}`);
+}
+
+export async function push(cfg) {
+  if (cfg.imageMode === "global") {
+    throw new Error(
+      "this project uses the shared global image — pushing here would publish to the global repo. " +
+        "Publish a new global version with: coding-container system create --tag vX.Y.Z"
+    );
+  }
+  if (!cfg.image.tag) {
+    throw new Error(
+      "custom image mode requires a tag: set image.tag in the project config or pass --tag"
+    );
+  }
+  await pushImage(cfg);
+}

package/src/commands/setup.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { globalConfigDir, globalConfigPath, PROJECT_ROOT } from "../config.js";
+import { ensureKeyPair } from "../utils/keys.js";
+
+// Values that differ per environment. When neither a flag nor a prompt supplies
+// one, the generated config gets a clearly-marked placeholder instead of a guess.
+const PLACEHOLDERS = {
+  registry: "your-registry.example.com/you",
+  nfsServer: "your-nas-ip-or-hostname",
+  nfsBasePath: "/path/to/shared/workspaces",
+};
+
+// Emit a YAML double-quoted scalar so special characters (":", "/", etc.) are safe.
+function yamlValue(v) {
+  return JSON.stringify(v);
+}
+
+function renderTemplate(dir, values) {
+  return `# coding-container global configuration (created by 'coding-container setup')
+#
+# Shared by every project. Layering, lowest to highest priority:
+#   built-in defaults -> THIS file -> the project's config.yaml -> CLI flags
+#
+# Relative paths in this file resolve against this file's directory.
+# The Dockerfile and the SSH key pair live next to this file:
+#   Dockerfile - the image build (copied here from the repo on first run)
+#   keys/      - the shared SSH key pair (per-project known_hosts alongside)
+
+image:
+  registry: ${yamlValue(values.registry)}
+  name: coding-container
+  # tag: optional local fallback (e.g. for offline 'validate --manifest').
+  # Normal deploys float on the cluster's coding-system ConfigMap:
+  #   coding-container system init --tag v1.0.0   (once, on a fresh cluster)
+  #   coding-container system get                 (show current/previous/maxEver)
+  # Set tag in a project config to pin that project to one global version.
+  # Single image build shared by all projects (Dockerfile copied next to this file).
+  dockerfile: ${path.join(dir, "Dockerfile")}
+  context: ${dir}
+  buildArgs:
+    BASE_IMAGE: ubuntu:26.04
+    NODE_VERSION: "22"
+    EXTRA_APT_PACKAGES: ""
+    EXTRA_NPM_PACKAGES: ""
+
+k8s:
+  namespace: coding
+  replicas: 1
+  serviceType: NodePort
+  nodePort: 30022   # default; override per project if several run at once
+  imagePullSecret: ""
+  resources:
+    requests:
+      cpu: 100m
+      memory: 128Mi
+    limits:
+      cpu: "2"
+      memory: 8Gi
+  env: {}
+  # Secret-backed env (values hidden from kubectl get deploy output):
+  # deployed as the managed <project>-env Secret and referenced via valueFrom.
+  # \${VAR} is expanded from your local shell at deploy time (missing vars
+  # fail fast); plain values stay in this file, so prefer \${} for real secrets.
+  # secretEnv:
+  #   OPENAI_API_KEY: \${OPENAI_API_KEY}
+
+nfs:
+  server: ${yamlValue(values.nfsServer)}
+  basePath: ${yamlValue(values.nfsBasePath)}
+  # Extra NAS folders mounted into the container alongside /workspace. Each
+  # subPath is a subfolder of basePath (created on first mount); readOnly
+  # (default false) blocks container writes.
+  # volumes:
+  #   - { subPath: shared-datasets, mountPath: /data, readOnly: true }
+
+ssh:
+  user: root
+  port: 22
+  keyName: id_ed25519
+  # keyDir intentionally unset: keys default to ./keys next to this file.
+  # Set ssh.keyDir in a project config to keep a per-project key pair instead.
+
+container:
+  workdir: /workspace
+  localPort: 2222
+`;
+}
+
+// Copy the Dockerfile from the repo into the global folder (the build context)
+// and add a .dockerignore so the SSH keys / this config never enter the build
+// context. Existing files are never overwritten.
+function provisionDockerfile(dir) {
+  const dst = path.join(dir, "Dockerfile");
+  if (fs.existsSync(dst)) {
+    console.log(`kept:    ${dst} (already exists, left untouched)`);
+  } else {
+    fs.copyFileSync(path.join(PROJECT_ROOT, "Dockerfile"), dst);
+    console.log(`created: ${dst} (copied from the repo)`);
+  }
+  const ignore = path.join(dir, ".dockerignore");
+  if (!fs.existsSync(ignore)) {
+    fs.writeFileSync(ignore, "keys/\nconfig.yaml\n*.pem\n");
+    console.log(`created: ${ignore}`);
+  }
+}
+
+// Ask for one environment value. A flag wins; otherwise an interactive prompt
+// (only on a real TTY); otherwise a clearly-marked placeholder. Never blocks
+// when run non-interactively.
+async function ask(rl, value, { flagName, label, example, placeholder }) {
+  if (value) return value;
+  if (rl) {
+    let text = "";
+    try {
+      text = await rl.question(`${label} [e.g. ${example}]: `);
+    } catch {
+      /* stdin closed (Ctrl-D) -> fall through to the placeholder */
+    }
+    const v = (text || "").trim();
+    if (v) return v;
+    console.warn(
+      `warning: no value for ${label.toLowerCase()}; wrote a placeholder. ` +
+        `Set it in the global config or re-run: coding-container setup --${flagName} <value>`
+    );
+  }
+  return placeholder;
+}
+
+// Collect the environment-specific values for a fresh global config.
+async function captureEnvironment(opts) {
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const rl = interactive
+    ? readline.createInterface({ input: process.stdin, output: process.stdout })
+    : null;
+  const willPrompt = Boolean(rl && (!opts.registry || !opts.nfsServer || !opts.nfsBasePath));
+  if (willPrompt) {
+    console.log("A few questions about your environment (Enter skips to a placeholder):");
+  }
+  try {
+    return {
+      registry: await ask(rl, opts.registry, {
+        flagName: "registry",
+        label: "Container registry",
+        example: "registry.example.com/you",
+        placeholder: PLACEHOLDERS.registry,
+      }),
+      nfsServer: await ask(rl, opts.nfsServer, {
+        flagName: "nfs-server",
+        label: "NFS server (NAS IP or hostname)",
+        example: "10.0.0.5",
+        placeholder: PLACEHOLDERS.nfsServer,
+      }),
+      nfsBasePath: await ask(rl, opts.nfsBasePath, {
+        flagName: "nfs-base-path",
+        label: "NFS base path (shared folder for per-project workspaces)",
+        example: "/workspaces",
+        placeholder: PLACEHOLDERS.nfsBasePath,
+      }),
+    };
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
+export async function setup(opts = {}) {
+  const dir = globalConfigDir();
+  fs.mkdirSync(dir, { recursive: true });
+
+  provisionDockerfile(dir);
+
+  const cfgFile = globalConfigPath();
+  if (fs.existsSync(cfgFile)) {
+    console.log(`kept:    ${cfgFile} (already exists, left untouched)`);
+  } else {
+    const values = await captureEnvironment(opts);
+    fs.writeFileSync(cfgFile, renderTemplate(dir, values));
+    console.log(`created: ${cfgFile}`);
+  }
+
+  const pair = ensureKeyPair(path.join(dir, "keys"), "id_ed25519");
+  console.log(`keys:    ${pair.private}`);
+
+  console.log(
+    `\nDone. Edit the global config if your environment differs (registry, NFS server),\n` +
+      `then run (once, on a fresh cluster): coding-container system init --tag v1.0.0\n` +
+      `and in any project folder: coding-container create`
+  );
+}

package/src/commands/ssh.js

@@ -0,0 +1,103 @@
+import net from "node:net";
+import path from "node:path";
+import { exec, run, start } from "../utils/exec.js";
+import { ensureKeyPair } from "../utils/keys.js";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function portAvailable(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(false));
+    srv.listen(port, "127.0.0.1", () => srv.close(() => resolve(true)));
+  });
+}
+
+function findFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.once("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const port = srv.address().port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+async function waitForReady(child, ms = 15000) {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (child.ready) return true;
+    await sleep(200);
+  }
+  return child.ready;
+}
+
+/**
+ * Per-project known_hosts file so ephemeral pod host keys (regenerated on
+ * every image build) never pollute the user's global known_hosts, and a
+ * changed key never blocks the connection.
+ */
+function sshCommonOptions(cfg, port, privateKey) {
+  return [
+    "-i",
+    privateKey,
+    "-p",
+    String(port),
+    "-o",
+    "StrictHostKeyChecking=no",
+    "-o",
+    `UserKnownHostsFile=${path.join(cfg.ssh.keyDirPath, `${cfg.project}-known_hosts`)}`,
+  ];
+}
+
+async function sshDirect(cfg, privateKey) {
+  const nodeIp = exec("kubectl", [
+    "get",
+    "nodes",
+    "-o",
+    "jsonpath={.items[0].status.addresses[?(@.type==\"InternalIP\")].address}",
+  ]);
+  await run("ssh", [...sshCommonOptions(cfg, cfg.k8s.nodePort, privateKey), `${cfg.ssh.user}@${nodeIp}`]);
+}
+
+export async function ssh(cfg, { direct = false } = {}) {
+  const { private: privateKey } = ensureKeyPair(cfg.ssh.keyDirPath, cfg.ssh.keyName);
+
+  if (direct) {
+    await sshDirect(cfg, privateKey);
+    return;
+  }
+
+  let localPort = cfg.container.localPort;
+  if (!(await portAvailable(localPort))) {
+    localPort = await findFreePort();
+    console.log(`Local port ${cfg.container.localPort} is in use, using ${localPort} instead`);
+  }
+  const pf = start("kubectl", [
+    "-n",
+    cfg.k8s.namespace,
+    "port-forward",
+    `svc/${cfg.project}`,
+    `${localPort}:${cfg.ssh.port}`,
+  ]);
+  pf.stdout.on("data", (d) => {
+    if (String(d).includes("Forwarding from")) pf.ready = true;
+  });
+  pf.stderr.on("data", (d) => process.stderr.write(d));
+
+  if (!(await waitForReady(pf))) {
+    pf.kill();
+    throw new Error(`port-forward to svc/${cfg.project} did not start in time`);
+  }
+
+  let failed = false;
+  try {
+    await run("ssh", [...sshCommonOptions(cfg, localPort, privateKey), `${cfg.ssh.user}@127.0.0.1`]);
+  } catch {
+    failed = true;
+  } finally {
+    pf.kill();
+  }
+  if (failed) process.exitCode = 255;
+}