context101-cli 0.1.0

package/src/checks.js

@@ -0,0 +1,165 @@
+import { SMOOTH_REGION } from "./defaults.js";
+import { commandExists } from "./exec.js";
+import { ensureDockerDaemon } from "./docker.js";
+
+/** Amplify CreateApp calls GitHub list-repository-webhooks with this token. */
+export function classifyGithubToken(token) {
+  const value = String(token ?? "").trim();
+  if (!value) return "missing";
+  if (value.startsWith("ghp_")) return "classic_pat";
+  if (value.startsWith("github_pat_")) return "fine_grained_pat";
+  if (value.startsWith("ghs_")) return "installation";
+  if (value.startsWith("gho_")) return "oauth";
+  if (value.startsWith("ghu_")) return "user_to_server";
+  return "unknown";
+}
+
+export function githubTokenWorksForAmplify(kind) {
+  return kind === "classic_pat" || kind === "fine_grained_pat";
+}
+
+function versionOf(exec, command, args, pattern) {
+  const result = exec({ command, args });
+  if (!result.ok) return null;
+  const text = `${result.stdout}\n${result.stderr}`;
+  const match = text.match(pattern);
+  return match ? match[1] : text.split("\n")[0];
+}
+
+export function runChecks({
+  exec,
+  env = {},
+  region = SMOOTH_REGION,
+  platform,
+  dryRun = false,
+  wait,
+} = {}) {
+  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+  const nodeOk = nodeMajor >= 20;
+  const npmVersion = versionOf(exec, "npm", ["-v"], /^(\d+\.\d+\.\d+)/m);
+  const awsVersion = versionOf(exec, "aws", ["--version"], /aws-cli\/(\S+)/);
+  const docker = ensureDockerDaemon({ exec, platform, dryRun, wait });
+  const ghOk = commandExists(exec, "gh");
+
+  let awsIdentity = null;
+  if (awsVersion) {
+    const identity = exec({
+      command: "aws",
+      args: ["sts", "get-caller-identity", "--output", "json"],
+      env,
+    });
+    if (identity.ok) {
+      try {
+        const parsed = JSON.parse(identity.stdout);
+        awsIdentity = {
+          account: parsed.Account ?? "",
+          arn: parsed.Arn ?? "",
+        };
+      } catch {
+        awsIdentity = { account: "", arn: "" };
+      }
+    }
+  }
+
+  let bootstrapped = null;
+  if (awsIdentity) {
+    const stack = exec({
+      command: "aws",
+      args: [
+        "cloudformation",
+        "describe-stacks",
+        "--stack-name",
+        "CDKToolkit",
+        "--region",
+        region,
+        "--query",
+        "Stacks[0].StackStatus",
+        "--output",
+        "text",
+      ],
+      env,
+    });
+    bootstrapped = stack.ok && /CREATE_COMPLETE|UPDATE_COMPLETE/.test(stack.stdout);
+  }
+
+  let ghLoggedIn = false;
+  let ghTokenKind = "missing";
+  if (ghOk) {
+    const token = exec({ command: "gh", args: ["auth", "token"] });
+    ghLoggedIn = token.ok && token.stdout.trim().length > 0;
+    if (ghLoggedIn) ghTokenKind = classifyGithubToken(token.stdout);
+  }
+
+  return {
+    node: { ok: nodeOk, version: process.versions.node },
+    npm: { ok: Boolean(npmVersion), version: npmVersion },
+    aws: { ok: Boolean(awsVersion), version: awsVersion, identity: awsIdentity },
+    docker,
+    gh: {
+      ok: ghOk,
+      loggedIn: ghLoggedIn,
+      tokenKind: ghTokenKind,
+      amplifyOk: githubTokenWorksForAmplify(ghTokenKind),
+    },
+    bootstrap: { ok: bootstrapped, region },
+  };
+}
+
+export function printChecks(checks, io) {
+  const { ok, warn, dim } = io;
+  const nodeLine = checks.node.ok
+    ? `node ${checks.node.version}`
+    : `node ${checks.node.version} (need 20+)`;
+  (checks.node.ok ? ok : warn)(nodeLine);
+  (checks.npm.ok ? ok : warn)(checks.npm.ok ? `npm ${checks.npm.version}` : "npm not found");
+  if (checks.aws.ok && checks.aws.identity) {
+    ok(`aws ${checks.aws.version}  account ${checks.aws.identity.account}`);
+  } else if (checks.aws.ok) {
+    warn(`aws ${checks.aws.version} — sts get-caller-identity failed`);
+  } else {
+    warn("aws cli not found");
+  }
+  if (checks.awsProfile) {
+    ok(`AWS profile ${checks.awsProfile}`);
+  } else if (checks.hasAwsKeys) {
+    ok("AWS access keys (no profile)");
+  } else if (checks.awsProfiles?.length > 1) {
+    warn(
+      `${checks.awsProfiles.length} AWS profiles (${checks.awsProfiles.join(", ")}) — pick one`
+    );
+  } else if (checks.awsProfiles?.length === 0) {
+    warn("no AWS profiles — will ask for access key and secret");
+  }
+  printDockerCheck(checks.docker, { ok, warn });
+  if (checks.gh.ok && checks.gh.amplifyOk) {
+    ok("gh (logged in with a PAT — usable if you watch a repo with Amplify)");
+  } else if (checks.gh.ok && checks.gh.loggedIn) {
+    warn(
+      `gh token is ${checks.gh.tokenKind} — if Amplify watches a repo, set CTX_GH_TOKEN=ghp_…`
+    );
+  } else if (checks.gh.ok) {
+    warn("gh found but not logged in — set CTX_GH_TOKEN only if Amplify watches a repo");
+  } else {
+    dim("gh optional — Amplify is skipped unless you pass --repo");
+  }
+}
+
+function printDockerCheck(docker, { ok, warn }) {
+  if (!docker) {
+    warn("docker not found (needed for CDK image assets)");
+    return;
+  }
+  if (!docker.installed) {
+    warn("docker not found (needed for CDK image assets)");
+    return;
+  }
+  if (docker.daemon && docker.started) {
+    ok(`docker (started ${docker.starter})`);
+    return;
+  }
+  if (docker.daemon) {
+    ok("docker");
+    return;
+  }
+  warn("docker daemon is not running (needed for CDK image assets)");
+}

package/src/clone.js

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_AMPLIFY_REPO } from "./defaults.js";
+import { findRepoRoot } from "./repo.js";
+
+export const CLONE_URL = DEFAULT_AMPLIFY_REPO;
+export const DEFAULT_CLONE_DIR = "context101";
+
+export function resolveCloneDir(cwd, dir) {
+  return path.resolve(cwd, dir || DEFAULT_CLONE_DIR);
+}
+
+export function ensureRepoRoot({
+  cwd,
+  dir,
+  exec,
+  io,
+  dryRun = false,
+  exists = existsSync,
+} = {}) {
+  const existing = findRepoRoot(cwd, exists);
+  if (existing) return { repoRoot: existing, cloned: false };
+
+  const target = resolveCloneDir(cwd, dir);
+  const already = findRepoRoot(target, exists);
+  if (already) return { repoRoot: already, cloned: false };
+
+  if (dryRun) {
+    io?.write?.(`Would clone ${CLONE_URL} into ${path.relative(cwd, target) || target}`);
+    return { repoRoot: target, cloned: false, wouldClone: true };
+  }
+
+  if (!exec) {
+    return { repoRoot: null, cloned: false, error: "git is required to clone Context101" };
+  }
+
+  io?.write?.(`Cloning ${CLONE_URL}…`);
+  if (!exists(path.dirname(target))) {
+    mkdirSync(path.dirname(target), { recursive: true });
+  }
+  const result = exec({
+    command: "git",
+    args: ["clone", "--depth", "1", CLONE_URL, target],
+    timeout: 120_000,
+  });
+  if (!result.ok) {
+    return {
+      repoRoot: null,
+      cloned: false,
+      error: result.stderr || result.stdout || "git clone failed",
+    };
+  }
+  const cloned = findRepoRoot(target, exists);
+  if (!cloned) {
+    return {
+      repoRoot: null,
+      cloned: false,
+      error: `cloned ${target} but it is not a Context101 checkout (needs cdk/ and web/)`,
+    };
+  }
+  io?.ok?.(`cloned into ${path.relative(cwd, cloned) || cloned}`);
+  return { repoRoot: cloned, cloned: true };
+}

package/src/config.js

@@ -0,0 +1,102 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { SECRET_KEYS } from "./defaults.js";
+import { findDeployEnvPath, parseEnvFile } from "./deploy-env-load.js";
+import { quoteShell } from "./env-file.js";
+import { isHostedContext101Url } from "./hosted-url.js";
+import { mask } from "./redact.js";
+import { findRepoRoot } from "./repo.js";
+import { banner, writers } from "./style.js";
+
+const SECRET_NAME = /TOKEN|SECRET|PASSWORD|PEPPER|KEY/i;
+const HOSTED_KEYS = new Set([
+  "BETTER_AUTH_URL",
+  "APP_URL",
+  "MARKETING_URL",
+  "MCP_PUBLIC_HOST",
+]);
+
+export function isSecretConfigKey(key) {
+  return SECRET_KEYS.includes(key) || SECRET_NAME.test(key);
+}
+
+export function formatConfig(values) {
+  const keys = Object.keys(values).sort();
+  if (keys.length === 0) return "No keys in the env file.";
+  return keys
+    .map((key) => {
+      const value = values[key] ?? "";
+      const shown = isSecretConfigKey(key) ? mask(value) : value;
+      return `${key}=${shown}`;
+    })
+    .join("\n");
+}
+
+export function upsertEnvLine(text, key, value) {
+  const line = `${key}=${quoteShell(value)}`;
+  const re = new RegExp(`^(\\s*(?:export\\s+)?${key}=).*`, "m");
+  if (re.test(text || "")) return (text || "").replace(re, line);
+  const base = !text ? "# Written by `context101 config set`. chmod 600.\n\n" : text;
+  const trimmed = base.endsWith("\n") ? base : `${base}\n`;
+  return `${trimmed}${line}\n`;
+}
+
+export async function runConfig(opts, ctx) {
+  const io = writers(ctx);
+  banner(ctx);
+
+  const repoRoot = findRepoRoot(ctx.cwd);
+  const filePath = findDeployEnvPath({
+    repoRoot,
+    envFile: opts.envFile,
+    home: opts.home,
+    cwd: ctx.cwd,
+  });
+
+  if (opts.configAction === "set") {
+    return writeConfig(opts, { io, filePath });
+  }
+
+  if (!filePath || !existsSync(filePath)) {
+    io.write("No deploy-env file yet.");
+    io.write("Next: context101 init");
+    return 0;
+  }
+
+  const text = await readFile(filePath, "utf8");
+  const { values } = parseEnvFile(text);
+  io.write(formatConfig(values));
+  io.write("");
+  return 0;
+}
+
+async function writeConfig(opts, { io, filePath }) {
+  const key = opts.configKey;
+  const value = opts.configValue;
+  if (!key) {
+    io.err("usage: context101 config set KEY=value");
+    return 1;
+  }
+  if (HOSTED_KEYS.has(key) && isHostedContext101Url(value)) {
+    io.err(
+      `${key} is the hosted Context101 product, not a self-host URL. Set a domain you own, or omit it.`
+    );
+    return 1;
+  }
+  if (!filePath) {
+    io.err("no deploy-env path. Re-run from a checkout or pass --deploy-env.");
+    return 1;
+  }
+
+  let text = "";
+  if (existsSync(filePath)) {
+    text = await readFile(filePath, "utf8");
+  }
+  const next = upsertEnvLine(text, key, value);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, next, { encoding: "utf8", mode: 0o600 });
+  await chmod(filePath, 0o600);
+  io.ok(`set ${key}`);
+  return 0;
+}

package/src/defaults.js

@@ -0,0 +1,28 @@
+export const SMOOTH_REGION = "us-east-1"; // pragma: allowlist secret
+export const DEFAULT_AMPLIFY_REPO = "https://github.com/jginorio/context101";
+export const TITAN_EMBED_MODEL = "amazon.titan-embed-text-v2:0";
+export const CLAUDE_IMPROVE_MODEL = "us.anthropic.claude-opus-4-7";
+export const DRIVER_NEON = "neon-http"; // pragma: allowlist secret
+export const DRIVER_POSTGRES = "postgres-js";
+export const APP_MODE = "self_hosted";
+export const ALLOW_PUBLIC_SIGNUP = "false";
+export const BILLING_ENABLED = "false";
+export const EXAMPLE_ENV_REL = "cdk/.deploy-env.example";
+export const REPO_ENV_REL = "cdk/.deploy-env";
+export const HOME_ENV_REL = ".context101/deploy-env";
+export const DEPLOY_CLI = "context101 deploy";
+export const LIST_CLI = "context101 list";
+export const DESTROY_CLI = "context101 destroy";
+export const NPX_CLI = "npx context101-cli";
+export const STACK_NAME = "Context101Stack";
+
+export const SECRET_KEYS = [
+  "CTX_TOKEN",
+  "CTX_GH_TOKEN",
+  "BETTER_AUTH_SECRET",
+  "MCP_TOKEN_PEPPER",
+  "DATABASE_URL",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+];

package/src/deploy-env-load.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { HOME_ENV_REL, REPO_ENV_REL } from "./defaults.js";
+
+export function unquoteEnvValue(raw) {
+  const trimmed = String(raw ?? "").trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1).replace(/\\([\\"$`])/g, "$1");
+  }
+  return trimmed;
+}
+
+export function parseEnvFile(text) {
+  const values = {};
+  const declared = new Set();
+  const lines = String(text ?? "").split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) continue;
+    declared.add(match[1]);
+    values[match[1]] = unquoteEnvValue(match[2]);
+  }
+  return { values, declared };
+}
+
+export function envFileDeclares(declared, key) {
+  return Boolean(declared && declared.has(key));
+}
+
+export function findDeployEnvPath({
+  repoRoot,
+  envFile,
+  home = false,
+  cwd,
+  exists = existsSync,
+} = {}) {
+  if (envFile) {
+    return path.isAbsolute(envFile)
+      ? envFile
+      : path.resolve(cwd ?? repoRoot ?? process.cwd(), envFile);
+  }
+  if (home) {
+    const homePath = path.join(homedir(), HOME_ENV_REL);
+    return exists(homePath) ? homePath : homePath;
+  }
+  if (repoRoot) {
+    const repoPath = path.join(repoRoot, ...REPO_ENV_REL.split("/"));
+    if (exists(repoPath)) return repoPath;
+  }
+  const homePath = path.join(homedir(), HOME_ENV_REL);
+  if (exists(homePath)) return homePath;
+  return repoRoot ? path.join(repoRoot, ...REPO_ENV_REL.split("/")) : null;
+}
+
+export function readDeployEnvFile(filePath, { readFile = readFileSync, exists = existsSync } = {}) {
+  if (!filePath || !exists(filePath)) {
+    return { path: filePath, values: {}, declared: new Set(), text: "", exists: false };
+  }
+  const text = readFile(filePath, "utf8");
+  const parsed = parseEnvFile(text);
+  return {
+    path: filePath,
+    values: parsed.values,
+    declared: parsed.declared,
+    text,
+    exists: true,
+  };
+}

package/src/deploy.js

@@ -0,0 +1,138 @@
+import { SMOOTH_REGION } from "./defaults.js";
+import {
+  assertDeployTokens,
+  buildCdkArgs,
+  formatCdkPreview,
+  resolveDeployContext,
+  runCdk,
+} from "./cdk-invoke.js";
+import { printChecks, runChecks } from "./checks.js";
+import { createExec } from "./exec.js";
+import { deployCommand } from "./plan.js";
+import { findRepoRoot } from "./repo.js";
+import { banner, writers } from "./style.js";
+
+export async function runDeploy(opts, ctx) {
+  return runCdkCommand(opts, ctx, opts.command || "deploy");
+}
+
+async function runCdkCommand(opts, ctx, action) {
+  const io = writers(ctx);
+  const exec = ctx.exec ?? createExec(ctx.env);
+
+  banner(ctx);
+  if (opts.dryRun) {
+    io.dim(`dry-run — ${action} nothing`);
+    io.write("");
+  }
+
+  const repoRoot = findRepoRoot(ctx.cwd);
+  if (!repoRoot) {
+    io.err("run this from a Context101 checkout (needs cdk/ and web/).");
+    return 1;
+  }
+
+  const env = ctx.env ?? {};
+  const checks = runChecks({
+    exec,
+    env,
+    region: SMOOTH_REGION,
+    dryRun: opts.dryRun,
+  });
+  printChecks(checks, io);
+  if (checks.docker?.hint && !checks.docker.daemon) {
+    io.write(checks.docker.hint);
+  }
+  io.write("");
+
+  let context;
+  let args;
+  try {
+    context = resolveDeployContext({
+      repoRoot,
+      env,
+      home: opts.home,
+      envFile: opts.envFile,
+      cwd: ctx.cwd,
+      exec,
+    });
+    assertDeployTokens(context, { action });
+    args = buildCdkArgs({
+      action,
+      seed: opts.seed,
+      context,
+      env,
+    });
+  } catch (error) {
+    if (error && error.code === "USAGE") {
+      io.err(error.message);
+      return 1;
+    }
+    throw error;
+  }
+
+  io.write(formatCdkPreview({ action, context, args, seed: opts.seed }));
+  io.write("");
+
+  if (opts.dryRun) {
+    io.write(`Would invoke: ${deployCommand(opts.seed)}`);
+    return 0;
+  }
+
+  if (action === "deploy") {
+    return startDeploy({
+      io,
+      ctx,
+      repoRoot,
+      seed: opts.seed,
+      env,
+      home: opts.home,
+      envFile: opts.envFile,
+      dockerDaemon: Boolean(checks.docker?.daemon),
+      dockerHint: checks.docker?.hint,
+    });
+  }
+
+  return (ctx.runDeploy ?? runCdk)({
+    repoRoot,
+    action,
+    seed: opts.seed,
+    env,
+    home: opts.home,
+    envFile: opts.envFile,
+    cwd: ctx.cwd,
+    exec,
+  });
+}
+
+export async function startDeploy({
+  io,
+  ctx,
+  repoRoot,
+  seed,
+  env,
+  home,
+  envFile,
+  dockerDaemon,
+  dockerHint,
+}) {
+  if (!dockerDaemon) {
+    io.err(
+      "not deploying: Docker daemon is not running. Start it, then run context101 deploy."
+    );
+    if (dockerHint) io.write(dockerHint);
+    return 1;
+  }
+
+  io.write("Deploying the stack…");
+  return (ctx.runDeploy ?? runCdk)({
+    repoRoot,
+    action: "deploy",
+    seed,
+    env,
+    home,
+    envFile,
+    cwd: ctx.cwd,
+    exec: ctx.exec,
+  });
+}

package/src/docker.js

@@ -0,0 +1,120 @@
+import { commandExists } from "./exec.js";
+
+export function dockerDaemonRunning(exec) {
+  const result = exec({
+    command: "docker",
+    args: ["info"],
+    timeout: 15_000,
+  });
+  return Boolean(result.ok);
+}
+
+export function dockerStartHint(platform = process.platform) {
+  const lines = [
+    "Start the Docker daemon, then run context101 deploy:",
+    "  · Docker Desktop — open the app and wait until it is running",
+    "  · Colima — colima start",
+  ];
+  if (platform === "linux") {
+    lines.push("  · Linux — sudo systemctl start docker");
+  }
+  return lines.join("\n");
+}
+
+export function listDockerStarters({ exec, platform = process.platform } = {}) {
+  const starters = [];
+  if (commandExists(exec, "colima")) {
+    starters.push({
+      name: "colima",
+      command: "colima",
+      args: ["start"],
+      timeout: 120_000,
+    });
+  }
+  if (platform === "darwin") {
+    starters.push({
+      name: "Docker Desktop",
+      command: "open",
+      args: ["-a", "Docker"],
+      timeout: 20_000,
+    });
+  }
+  if (platform === "linux" && commandExists(exec, "systemctl")) {
+    starters.push({
+      name: "systemctl",
+      command: "systemctl",
+      args: ["start", "docker"],
+      timeout: 20_000,
+    });
+  }
+  return starters;
+}
+
+export function ensureDockerDaemon({
+  exec,
+  platform = process.platform,
+  dryRun = false,
+  wait = defaultWait,
+  attempts = 8,
+} = {}) {
+  if (!commandExists(exec, "docker")) {
+    return {
+      installed: false,
+      daemon: false,
+      started: false,
+      starter: null,
+      hint: "Install Docker (or Colima) so CDK can build the wiki-gen and MCP images.",
+    };
+  }
+  if (dockerDaemonRunning(exec)) {
+    return {
+      installed: true,
+      daemon: true,
+      started: false,
+      starter: null,
+      hint: null,
+    };
+  }
+  if (dryRun) {
+    return {
+      installed: true,
+      daemon: false,
+      started: false,
+      starter: null,
+      hint: dockerStartHint(platform),
+    };
+  }
+
+  for (const starter of listDockerStarters({ exec, platform })) {
+    const launched = exec({
+      command: starter.command,
+      args: starter.args,
+      timeout: starter.timeout,
+    });
+    if (!launched.ok) continue;
+    for (let i = 0; i < attempts; i++) {
+      if (dockerDaemonRunning(exec)) {
+        return {
+          installed: true,
+          daemon: true,
+          started: true,
+          starter: starter.name,
+          hint: null,
+        };
+      }
+      wait(500);
+    }
+  }
+
+  return {
+    installed: true,
+    daemon: false,
+    started: false,
+    starter: null,
+    hint: dockerStartHint(platform),
+  };
+}
+
+function defaultWait(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}