context101-cli 0.1.0

package/src/parse-args.js

@@ -0,0 +1,320 @@
+import { DRIVER_NEON, DRIVER_POSTGRES } from "./defaults.js";
+
+const FLAG_HELP = `
+Usage: context101 <command> [options]
+
+  init                 write a local secrets file (default)
+  deploy               deploy the AWS stack (loads deploy-env, invokes cdk)
+  diff                 cdk diff with the same context flags
+  synth                cdk synth with the same context flags
+  list, ls             list Context101 CloudFormation deployments
+  destroy, remove, rm  tear down a listed stack (name required)
+  config               show deploy-env keys (values redacted)
+  config set KEY=value write one key (chmod 600; value is not printed)
+
+CDK fails closed: a bare \`cdk deploy\` without \`-c token=\` throws
+instead of deleting MCP / Amplify. The CLI is the front door.
+
+  context101 init
+  context101 deploy
+  npx context101-cli init
+  npx context101-cli deploy
+
+  --dry-run              print the plan; write nothing, deploy nothing
+  --yes, -y              accept defaults (creates RDS if no --database-url)
+  --force                overwrite an existing env file
+  --dir <path>           clone into this directory when not in a checkout
+  --deploy-env <path>    default: <repo>/cdk/.deploy-env
+  --home                 write ~/.context101/deploy-env instead
+  --database-url <url>   Postgres URL (also reads DATABASE_URL)
+  --create-rds           CDK provisions RDS Postgres (default when no URL)
+  --database-driver      ${DRIVER_NEON} | ${DRIVER_POSTGRES}
+  --database-prepare     true | false
+  --aws-profile <name>   also reads AWS_PROFILE; required with --yes
+                         when more than one profile exists
+  --aws-access-key-id    used when no profile exists (also AWS_ACCESS_KEY_ID)
+  --aws-secret-access-key
+                         used when no profile exists (also AWS_SECRET_ACCESS_KEY)
+  --repo <url>           watch this GitHub repo with Amplify
+                         (default: skip Amplify, unless gh login is jginorio)
+  --embed-model <id>     optional CDK default embedding model
+                         (brains still pick any Titan/Cohere model in the app)
+  --skip-bedrock-access  do not request Bedrock model access during init
+  --seed                 first deploy uploads knowledge/ once
+  --deploy               deploy after writing (combine with --yes)
+
+deploy / diff / synth:
+  --seed                 upload knowledge/ once (first deploy only)
+  --deploy-env <path>
+  --home
+  --dry-run              print the command; invoke nothing
+
+list:
+  --aws-profile <name>
+  --aws-access-key-id
+  --aws-secret-access-key
+
+destroy <StackName>:
+  --yes, -y              skip the confirmation prompt
+  --aws-profile <name>
+  --aws-access-key-id
+  --aws-secret-access-key
+  --deploy-env <path>
+  --home
+  --dry-run              print the plan; destroy nothing
+
+config:
+  --deploy-env <path>
+  --home
+
+From this checkout (after npm install):
+  npm run context101 -- init
+  npm run context101 -- deploy
+  npx context101-cli init
+  npx context101-cli deploy
+  context101 list
+  context101 destroy Context101Stack
+  context101 config
+
+npx context101 (unscoped) downloads Context7's MCP from npm — unrelated.
+The publishable CLI is context101-cli; the bin name is context101.
+`.trim();
+
+const INIT_ONLY = new Set([
+  "--yes",
+  "-y",
+  "--force",
+  "--deploy",
+  "--dir",
+  "--database-url",
+  "--create-rds",
+  "--database-driver",
+  "--database-prepare",
+  "--aws-profile",
+  "--aws-access-key-id",
+  "--aws-secret-access-key",
+  "--repo",
+  "--embed-model",
+  "--skip-bedrock-access",
+]);
+
+const DESTROY_FROM_INIT = new Set([
+  "--yes",
+  "-y",
+  "--aws-profile",
+  "--aws-access-key-id",
+  "--aws-secret-access-key",
+]);
+
+const LIST_FROM_INIT = new Set([
+  "--aws-profile",
+  "--aws-access-key-id",
+  "--aws-secret-access-key",
+]);
+
+const CDK_COMMANDS = new Set(["deploy", "diff", "synth"]);
+
+const COMMANDS = {
+  init: "init",
+  deploy: "deploy",
+  diff: "diff",
+  synth: "synth",
+  list: "list",
+  ls: "list",
+  destroy: "destroy",
+  remove: "destroy",
+  rm: "destroy",
+  config: "config",
+};
+
+export function helpText() {
+  return FLAG_HELP;
+}
+
+export function parseArgs(argv) {
+  const opts = {
+    command: "init",
+    help: false,
+    dryRun: false,
+    yes: false,
+    force: false,
+    deploy: false,
+    seed: false,
+    home: false,
+    dir: null,
+    envFile: null,
+    databaseUrl: null,
+    createRds: false,
+    databaseDriver: null,
+    databasePrepare: null,
+    awsProfile: null,
+    awsAccessKeyId: null,
+    awsSecretAccessKey: null,
+    repo: null,
+    embedModel: null,
+    skipBedrockAccess: false,
+    stackName: null,
+    configAction: "show",
+    configKey: null,
+    configValue: null,
+  };
+
+  const args = [...argv];
+  if (args.length === 0) return opts;
+
+  const first = args[0];
+  if (COMMANDS[first]) {
+    opts.command = COMMANDS[first];
+    args.shift();
+  } else if (first === "help" || first === "--help" || first === "-h") {
+    opts.help = true;
+    return opts;
+  } else if (!first.startsWith("-")) {
+    const err = new Error(`unknown command: ${first}`);
+    err.code = "USAGE";
+    throw err;
+  }
+
+  if (opts.command === "config" && args[0] === "set") {
+    args.shift();
+    const pair = args.shift();
+    if (!pair || !pair.includes("=")) {
+      const err = new Error("usage: context101 config set KEY=value");
+      err.code = "USAGE";
+      throw err;
+    }
+    const eq = pair.indexOf("=");
+    opts.configAction = "set";
+    opts.configKey = pair.slice(0, eq);
+    opts.configValue = pair.slice(eq + 1);
+  }
+
+  while (args.length) {
+    const arg = args.shift();
+    if (opts.command === "destroy" && !arg.startsWith("-")) {
+      if (opts.stackName) {
+        const err = new Error("destroy takes one stack name");
+        err.code = "USAGE";
+        throw err;
+      }
+      opts.stackName = arg;
+      continue;
+    }
+    if (!flagAllowed(opts.command, arg)) {
+      const err = new Error(
+        opts.command === "init" ? `unknown flag: ${arg}` : `${arg} is an init option`
+      );
+      err.code = "USAGE";
+      throw err;
+    }
+    if (arg === "--seed" && !CDK_COMMANDS.has(opts.command) && opts.command !== "init") {
+      const err = new Error(`--seed is a deploy option`);
+      err.code = "USAGE";
+      throw err;
+    }
+    switch (arg) {
+      case "--help":
+      case "-h":
+        opts.help = true;
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--yes":
+      case "-y":
+        opts.yes = true;
+        break;
+      case "--force":
+        opts.force = true;
+        break;
+      case "--deploy":
+        opts.deploy = true;
+        break;
+      case "--seed":
+        opts.seed = true;
+        break;
+      case "--home":
+        opts.home = true;
+        break;
+      case "--dir":
+        opts.dir = needValue(arg, args);
+        break;
+      case "--deploy-env":
+        opts.envFile = needValue(arg, args);
+        break;
+      case "--database-url":
+        opts.databaseUrl = needValue(arg, args);
+        break;
+      case "--create-rds":
+        opts.createRds = true;
+        break;
+      case "--database-driver":
+        opts.databaseDriver = parseDriver(needValue(arg, args));
+        break;
+      case "--database-prepare":
+        opts.databasePrepare = parseBool(needValue(arg, args));
+        break;
+      case "--aws-profile":
+        opts.awsProfile = needValue(arg, args);
+        break;
+      case "--aws-access-key-id":
+        opts.awsAccessKeyId = needValue(arg, args);
+        break;
+      case "--aws-secret-access-key":
+        opts.awsSecretAccessKey = needValue(arg, args);
+        break;
+      case "--repo":
+        opts.repo = needValue(arg, args);
+        break;
+      case "--embed-model":
+        opts.embedModel = needValue(arg, args);
+        break;
+      case "--skip-bedrock-access":
+        opts.skipBedrockAccess = true;
+        break;
+      default: {
+        const err = new Error(`unknown flag: ${arg}`);
+        err.code = "USAGE";
+        throw err;
+      }
+    }
+  }
+
+  return opts;
+}
+
+function flagAllowed(command, arg) {
+  if (!INIT_ONLY.has(arg)) return true;
+  if (command === "init") return true;
+  if (command === "destroy") return DESTROY_FROM_INIT.has(arg);
+  if (command === "list") return LIST_FROM_INIT.has(arg);
+  if (command === "config") return arg === "--home";
+  return false;
+}
+
+function needValue(flag, args) {
+  const value = args.shift();
+  if (!value || value.startsWith("-")) {
+    const err = new Error(`${flag} needs a value`);
+    err.code = "USAGE";
+    throw err;
+  }
+  return value;
+}
+
+function parseDriver(value) {
+  if (value === DRIVER_NEON || value === DRIVER_POSTGRES) return value;
+  const err = new Error(
+    `--database-driver must be ${DRIVER_NEON} or ${DRIVER_POSTGRES}`
+  );
+  err.code = "USAGE";
+  throw err;
+}
+
+function parseBool(value) {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  const err = new Error(`--database-prepare must be true or false`);
+  err.code = "USAGE";
+  throw err;
+}

package/src/plan.js

@@ -0,0 +1,111 @@
+import {
+  CLAUDE_IMPROVE_MODEL,
+  DEPLOY_CLI,
+  TITAN_EMBED_MODEL,
+} from "./defaults.js";
+
+export function deployCommand(seed) {
+  return seed ? `${DEPLOY_CLI} --seed` : DEPLOY_CLI;
+}
+
+export function formatDryRun(plan) {
+  const access = plan.requestBedrockAccess
+    ? "request access for all Titan/Cohere embeddings (including new ids Bedrock lists; users pick later in the app)"
+    : "skip requesting access";
+  const embedDefault = plan.embedModelId
+    ? `${plan.embedModelId} (--embed-model)`
+    : `${TITAN_EMBED_MODEL} (CDK default)`;
+  const models = plan.embeddingModels?.length
+    ? `     ${plan.embeddingModels.map((m) => m.id).join(", ")}`
+    : null;
+  const lines = [
+    "Plan (dry-run — nothing will be written, nothing will be deployed)",
+    "",
+    `  1. Local tools: Node 20+, npm, AWS CLI v2, Docker, optional gh`,
+    plan.dockerInstalled && plan.dockerDaemon === false
+      ? "     docker daemon is not running — start it before deploy"
+      : null,
+    `  2. AWS account in ${plan.region} (smooth path)`,
+    plan.account
+      ? `     account ${plan.account}`
+      : "     aws sts get-caller-identity not confirmed",
+    plan.awsProfile
+      ? `     profile ${plan.awsProfile}`
+      : plan.awsProfiles?.length > 1
+        ? `     would ask which profile: ${plan.awsProfiles.join(", ")}`
+        : plan.hasAwsKeys
+          ? "     using AWS access keys (written to the secrets file)"
+          : "     would ask for AWS access key and secret",
+    `  3. CDK bootstrap: ${bootstrapLabel(plan)}`,
+    `  4. Bedrock embeddings: ${access}`,
+    models,
+    `     default: ${embedDefault}`,
+    `     Claude (${CLAUDE_IMPROVE_MODEL}) for Improve — wiki is paused; skip`,
+    plan.repository
+      ? `  5. Amplify: watch ${plan.repository}`
+      : "  5. Amplify: skipped (stack only — no GitHub-watched web app)",
+    plan.repository
+      ? "     written as REPOSITORY in the secrets file (CDK reads it as context)"
+      : "     a found-the-repo operator does not watch this checkout by default",
+    plan.createRds
+      ? "  6. Postgres: CDK creates RDS (db.t3.micro, public) — no DATABASE_URL in the secrets file"
+      : `  6. Postgres: DATABASE_URL ${plan.hasDatabaseUrl ? "provided" : "missing"}, driver ${plan.databaseDriver}, prepare ${
+          plan.databasePrepare ? "true" : "false"
+        }`,
+    `  7. Generate BETTER_AUTH_SECRET, MCP_TOKEN_PEPPER, CTX_TOKEN (not printed)`,
+    `     APP_MODE=self_hosted  ALLOW_PUBLIC_SIGNUP=false  BILLING_ENABLED=false`,
+    `     BETTER_AUTH_URL / APP_URL omitted — CDK uses the Amplify default domain`,
+    "     or a domain you own. Never the hosted Context101 product.",
+    `  8. Write ${plan.envDisplay} (chmod 600)`,
+    plan.envExists
+      ? "     file already exists — dry-run would refuse without --force"
+      : "     file does not exist yet",
+    `  9. Next: ${deployCommand(plan.seed)}`,
+    "     first deploy: add --seed to upload knowledge/ once",
+    plan.repository
+      ? " 10. After web is up: /setup on the Amplify domain (first admin)"
+      : " 10. Amplify skipped — run web/ locally, or re-run with --repo to watch a GitHub repo",
+    "",
+    `Would write: ${plan.envDisplay}`,
+    plan.deploy
+      ? `Would deploy after writing: ${deployCommand(plan.seed)}`
+      : "Would not deploy.",
+  ];
+  return lines.filter((line) => line !== null).join("\n");
+}
+
+function bootstrapLabel(plan) {
+  if (plan.bootstrapped === true) return `already done in ${plan.region}`;
+  if (plan.bootstrapped === false && plan.account) {
+    return `needed — npx cdk bootstrap aws://${plan.account}/${plan.region}`;
+  }
+  return "not checked (no AWS identity)";
+}
+
+export function nextSteps(plan) {
+  const rds = plan.createRds
+    ? "CDK will create RDS Postgres and apply the control-plane schema. Fetch the secret via ControlPlaneDbSecretArn — the password is never printed."
+    : null;
+  const next = [
+    `Next: ${deployCommand(plan.seed)}`,
+    plan.seed ? null : "First time? add --seed to upload the example knowledge/ files once.",
+    rds,
+  ];
+  if (plan.repository) {
+    return [
+      ...next,
+      "After Amplify is up (~4 min), open /setup on WebAppDefaultDomain (or your own domain).",
+      "Leave BETTER_AUTH_URL / APP_URL unset unless you bring your own host. CDK fills the Amplify default.",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+  return [
+    ...next,
+    "Amplify is skipped — this deploy is the AWS stack only (no GitHub-watched web app).",
+    "Run the web app from web/, or re-run init with --repo when you want Amplify.",
+    "Leave BETTER_AUTH_URL / APP_URL unset unless you bring your own host.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}

package/src/prompt.js

@@ -0,0 +1,104 @@
+import {
+  DRIVER_NEON,
+  DRIVER_POSTGRES,
+  SMOOTH_REGION,
+} from "./defaults.js";
+import { inferDriver, inferPrepare } from "./env-file.js";
+import { normalizeRepoUrl } from "./repo.js";
+
+export async function promptAnswers({ defaults, io, exec, env }) {
+  const { confirm, input, password, select } = await import("@inquirer/prompts");
+
+  io.write("This writes a local secrets file. Deploy afterwards with:");
+  io.write("  context101 deploy");
+  io.write("Press ^C to quit.");
+  io.write("");
+
+  const region = await input({
+    message: "AWS region",
+    default: defaults.region ?? SMOOTH_REGION,
+  });
+  if (region !== SMOOTH_REGION) {
+    io.warn(`${SMOOTH_REGION} is the smooth path (S3 Vectors + Bedrock).`);
+  }
+
+  const watchByDefault = Boolean(defaults.repository);
+  const amplifyMode = await select({
+    message: "Amplify frontend",
+    default: watchByDefault ? "watch" : "skip",
+    choices: [
+      {
+        name: "Skip — deploy the stack only (no GitHub-watched web app)",
+        value: "skip",
+      },
+      { name: "Watch a GitHub repo", value: "watch" },
+    ],
+  });
+
+  let repository = "";
+  if (amplifyMode === "watch") {
+    repository = normalizeRepoUrl(
+      await input({
+        message: "GitHub repo Amplify should watch",
+        default: defaults.repository || defaults.suggestedRepo || "",
+        validate: (value) =>
+          value ? true : "needed if Amplify should watch a repo",
+      })
+    );
+  }
+
+  const dbMode = await select({
+    message: "Postgres control plane",
+    default: defaults.databaseUrl ? "url" : "rds",
+    choices: [
+      {
+        name: "Create RDS — CDK provisions Postgres (db.t3.micro, public)",
+        value: "rds",
+      },
+      {
+        name: "I have a DATABASE_URL (Neon / Supabase / existing Postgres)",
+        value: "url",
+      },
+    ],
+  });
+
+  let databaseUrl = "";
+  let createRds = dbMode === "rds";
+  let databaseDriver = DRIVER_POSTGRES;
+  let databasePrepare = true;
+  if (dbMode === "url") {
+    databaseUrl = await password({
+      message: "DATABASE_URL",
+      mask: true,
+      validate: (value) =>
+        value ? true : "needed unless CDK creates RDS",
+    });
+    createRds = false;
+    const inferredDriver = inferDriver(databaseUrl);
+    databaseDriver = await select({
+      message: "DATABASE_DRIVER",
+      default: inferredDriver,
+      choices: [
+        { name: `${DRIVER_NEON} (Neon)`, value: DRIVER_NEON },
+        { name: `${DRIVER_POSTGRES} (Supabase / RDS / local)`, value: DRIVER_POSTGRES },
+      ],
+    });
+    databasePrepare = await confirm({
+      message: "DATABASE_PREPARE (false for Supabase transaction pooler)",
+      default: inferPrepare(databaseUrl),
+    });
+  }
+
+  return {
+    region,
+    repository,
+    embedModelId: defaults.embedModelId || "",
+    createRds,
+    databaseUrl,
+    databaseDriver,
+    databasePrepare,
+    awsProfile: defaults.awsProfile ?? null,
+    awsAccessKeyId: defaults.awsAccessKeyId ?? null,
+    awsSecretAccessKey: defaults.awsSecretAccessKey ?? null,
+  };
+}

package/src/redact.js

@@ -0,0 +1,28 @@
+import { SECRET_KEYS } from "./defaults.js";
+
+export function mask(value) {
+  if (!value) return "(empty)";
+  if (value.length <= 8) return "…";
+  return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+
+export function collectSecrets(values = {}) {
+  const secrets = [];
+  for (const key of SECRET_KEYS) {
+    const value = values[key];
+    if (typeof value === "string" && value.length > 0) secrets.push(value);
+  }
+  return secrets;
+}
+
+export function outputContainsSecret(text, secrets) {
+  if (!text) return false;
+  return secrets.some((secret) => secret && text.includes(secret));
+}
+
+export function assertNoSecrets(text, secrets, label = "output") {
+  const hit = (secrets || []).find((secret) => secret && text.includes(secret));
+  if (hit) {
+    throw new Error(`${label} leaked a secret`);
+  }
+}

package/src/repo.js

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { DEFAULT_AMPLIFY_REPO, HOME_ENV_REL, REPO_ENV_REL } from "./defaults.js";
+
+export function isContext101Checkout(dir, exists = existsSync) {
+  const web = exists(path.join(dir, "web", "package.json"));
+  const cdk =
+    exists(path.join(dir, "cdk", "cdk.json")) ||
+    exists(path.join(dir, "cdk", "bin", "context101.ts")) ||
+    exists(path.join(dir, "cdk", "deploy.sh"));
+  return web && cdk;
+}
+
+export function findRepoRoot(startDir, exists = existsSync) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    if (isContext101Checkout(dir, exists)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function defaultEnvPath(repoRoot, { home = false } = {}) {
+  if (home) return path.join(homedir(), HOME_ENV_REL);
+  return path.join(repoRoot, ...REPO_ENV_REL.split("/"));
+}
+
+export function resolveEnvPath(repoRoot, opts) {
+  if (opts.envFile) {
+    return path.isAbsolute(opts.envFile)
+      ? opts.envFile
+      : path.resolve(opts.cwd ?? repoRoot, opts.envFile);
+  }
+  return defaultEnvPath(repoRoot, { home: opts.home });
+}
+
+export function normalizeRepoUrl(raw) {
+  if (!raw) return "";
+  const trimmed = raw.trim();
+  const ssh = trimmed.match(/^git@github\.com:(.+?)(?:\.git)?$/);
+  if (ssh) return `https://github.com/${ssh[1]}`;
+  try {
+    const parsed = new URL(trimmed);
+    if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+      parsed.username = "";
+      parsed.password = "";
+      return parsed.toString().replace(/\.git\/?$/, "").replace(/\/$/, "");
+    }
+  } catch {
+    // not a URL
+  }
+  return trimmed.replace(/\.git$/, "");
+}
+
+export function detectGitRemote(exec, repoRoot) {
+  const result = exec({
+    command: "git",
+    args: ["-C", repoRoot, "remote", "get-url", "origin"],
+  });
+  if (!result.ok) return "";
+  return normalizeRepoUrl(result.stdout.split("\n")[0] || "");
+}
+
+export function readHardcodedRepo(stackSource) {
+  const match = stackSource.match(/repository:\s*"(https:\/\/github\.com\/[^"]+)"/);
+  return match ? match[1] : DEFAULT_AMPLIFY_REPO;
+}
+
+export function displayEnvPath(filePath, repoRoot) {
+  if (filePath.startsWith(repoRoot + path.sep)) {
+    return path.relative(repoRoot, filePath);
+  }
+  if (filePath.startsWith(homedir())) {
+    return `~${filePath.slice(homedir().length)}`;
+  }
+  return filePath;
+}

package/src/secrets.js

@@ -0,0 +1,9 @@
+import { randomBytes } from "node:crypto";
+
+export function generateSecret() {
+  return randomBytes(32).toString("base64");
+}
+
+export function generateCtxToken() {
+  return randomBytes(32).toString("base64url");
+}