context101-cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context101-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Context101 self-host CLI. Use `npx context101-cli` or the `context101` bin. The public npm package named context101 is Context7's MCP, not this tool.",
   "type": "module",
@@ -19,8 +19,5 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.8.4"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/clone.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
-import { DEFAULT_AMPLIFY_REPO } from "./defaults.js";
+import { DEFAULT_AMPLIFY_REPO, HOME_SRC_REL } from "./defaults.js";
 import { findRepoRoot } from "./repo.js";
 
 export const CLONE_URL = DEFAULT_AMPLIFY_REPO;
@@ -10,6 +11,10 @@ export function resolveCloneDir(cwd, dir) {
   return path.resolve(cwd, dir || DEFAULT_CLONE_DIR);
 }
 
+export function homeSrcDir(homeDir = homedir()) {
+  return path.join(homeDir, HOME_SRC_REL);
+}
+
 export function ensureRepoRoot({
   cwd,
   dir,
@@ -17,16 +22,27 @@ export function ensureRepoRoot({
   io,
   dryRun = false,
   exists = existsSync,
+  homeDir,
+  preferHomeClone = false,
 } = {}) {
   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 };
+  const localTarget = resolveCloneDir(cwd, dir);
+  const alreadyLocal = findRepoRoot(localTarget, exists);
+  if (alreadyLocal) return { repoRoot: alreadyLocal, cloned: false };
+
+  const resolvedHome = homeDir ?? homedir();
+  const homeTarget = homeSrcDir(resolvedHome);
+  if (preferHomeClone) {
+    const alreadyHome = findRepoRoot(homeTarget, exists);
+    if (alreadyHome) return { repoRoot: alreadyHome, cloned: false };
+  }
+
+  const target = preferHomeClone && !dir ? homeTarget : localTarget;
 
   if (dryRun) {
-    io?.write?.(`Would clone ${CLONE_URL} into ${path.relative(cwd, target) || target}`);
+    io?.write?.(`Would clone ${CLONE_URL} into ${displayCloneTarget(cwd, target, resolvedHome)}`);
     return { repoRoot: target, cloned: false, wouldClone: true };
   }
 
@@ -58,6 +74,13 @@ export function ensureRepoRoot({
       error: `cloned ${target} but it is not a Context101 checkout (needs cdk/ and web/)`,
     };
   }
-  io?.ok?.(`cloned into ${path.relative(cwd, cloned) || cloned}`);
+  io?.ok?.(`cloned into ${displayCloneTarget(cwd, cloned, resolvedHome)}`);
   return { repoRoot: cloned, cloned: true };
 }
+
+function displayCloneTarget(cwd, target, homeDir) {
+  if (homeDir && (target === homeDir || target.startsWith(homeDir + path.sep))) {
+    return `~${target.slice(homeDir.length)}`;
+  }
+  return path.relative(cwd, target) || target;
+}

package/src/config.js

@@ -52,6 +52,7 @@ export async function runConfig(opts, ctx) {
     envFile: opts.envFile,
     home: opts.home,
     cwd: ctx.cwd,
+    homeDir: ctx.homeDir,
   });
 
   if (opts.configAction === "set") {
@@ -85,7 +86,7 @@ async function writeConfig(opts, { io, filePath }) {
     return 1;
   }
   if (!filePath) {
-    io.err("no deploy-env path. Re-run from a checkout or pass --deploy-env.");
+    io.err("no deploy-env path. Pass --home or --deploy-env.");
     return 1;
   }
 

package/src/defaults.js

@@ -10,6 +10,7 @@ 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 HOME_SRC_REL = ".context101/src";
 export const DEPLOY_CLI = "context101 deploy";
 export const LIST_CLI = "context101 list";
 export const DESTROY_CLI = "context101 destroy";

package/src/deploy-env-load.js

@@ -39,23 +39,22 @@ export function findDeployEnvPath({
   home = false,
   cwd,
   exists = existsSync,
+  homeDir,
 } = {}) {
+  const resolvedHome = homeDir ?? homedir();
   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;
-  }
+  const homePath = path.join(resolvedHome, HOME_ENV_REL);
+  if (home) return 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;
+  return repoRoot ? path.join(repoRoot, ...REPO_ENV_REL.split("/")) : homePath;
 }
 
 export function readDeployEnvFile(filePath, { readFile = readFileSync, exists = existsSync } = {}) {

package/src/init.js

@@ -15,10 +15,7 @@ import {
   printChecks,
   runChecks,
 } from "./checks.js";
-import {
-  formatAccessResult,
-  requestEmbeddingModelAccess,
-} from "./bedrock-access.js";
+import { requestEmbeddingModelAccess } from "./bedrock-access.js";
 import {
   isKnownEmbeddingModel,
   listEmbeddingModels,
@@ -267,11 +264,22 @@ export async function runInit(opts, ctx) {
       "no Amplify-capable GitHub PAT yet — set CTX_GH_TOKEN to a ghp_ or github_pat_ token before deploy"
     );
   }
-  io.write("");
-  io.write(nextSteps(plan));
-  io.write("");
 
-  if (!answers.deploy) return 0;
+  let deploy = Boolean(answers.deploy);
+  if (!deploy && !opts.yes && tty) {
+    deploy = Boolean(
+      await askDeployNow(ctx, {
+        createRds: Boolean(answers.createRds),
+        seed: Boolean(answers.seed),
+        repository: answers.repository || "",
+      })
+    );
+  }
+
+  if (!deploy) {
+    io.write(nextSteps({ seed: answers.seed }));
+    return 0;
+  }
 
   if (answers.repository && !githubReadyForAmplify(checks, answers)) {
     io.err(
@@ -391,15 +399,28 @@ function withAwsAuth(env, { profile, accessKeyId, secretAccessKey } = {}) {
   return next;
 }
 
+async function askDeployNow(ctx, details) {
+  if (typeof ctx.confirmDeploy === "function") {
+    return ctx.confirmDeploy(details);
+  }
+  const { promptDeployNow } = await import("./prompt.js");
+  return promptDeployNow(details);
+}
+
 function printBedrockAccess(results, io) {
-  io.write("Bedrock embedding access:");
-  for (const result of results) {
-    const line = formatAccessResult(result);
-    if (result.status === "needs-console" || result.status === "failed") {
-      io.warn(line);
-    } else {
-      io.dim(`  ${line}`);
-    }
+  const problems = (results || []).filter(
+    (result) => result.status === "needs-console" || result.status === "failed"
+  );
+  const granted = (results || []).filter((result) => result.status === "granted").length;
+  if (problems.length) {
+    const ids = problems
+      .slice(0, 2)
+      .map((result) => result.id)
+      .join(", ");
+    const extra = problems.length > 2 ? ` (+${problems.length - 2})` : "";
+    io.warn(`Bedrock: enable ${ids}${extra} in console → Model access`);
+  } else if (granted) {
+    io.ok("Bedrock access granted");
   }
 }
 

package/src/main.js

@@ -19,8 +19,10 @@ export async function main(argv, ctx) {
     throw error;
   }
 
-  if (opts.help) {
-    io.write(helpText());
+  if (opts.help || opts.command === "help") {
+    const topic =
+      opts.helpTopic ?? (opts.command !== "help" ? opts.command : null);
+    io.write(helpText(topic));
     return 0;
   }
 

package/src/parse-args.js

@@ -1,84 +1,90 @@
 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)
+const COMMAND_LINES = [
+  ["init", "write deploy-env (default); TTY asks to deploy"],
+  ["deploy", "deploy the AWS stack"],
+  ["diff", "cdk diff with the same context"],
+  ["synth", "cdk synth with the same context"],
+  ["list", "list Context101 CloudFormation stacks"],
+  ["destroy", "tear down a listed stack (name required)"],
+  ["config", "show deploy-env keys (values redacted)"],
+  ["config set", "write one key (chmod 600; value is not printed)"],
+  ["help", "list commands"],
+];
+
+const TOPIC_HELP = {
+  init: `init — write deploy-env (default); TTY asks to deploy
+
+  --dry-run
+  --yes, -y              accept defaults (creates RDS if no --database-url);
+                         required --aws-profile when several exist
   --force                overwrite an existing env file
-  --dir <path>           clone into this directory when not in a checkout
+  --dir <path>           clone here 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)
+  --home                 ~/.context101/deploy-env
+  --database-url <url>
+  --create-rds           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-profile <name>
+  --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)
+  --repo <url>           Amplify watch (skipped unless gh login is jginorio)
+  --embed-model <id>
+  --skip-bedrock-access
+  --seed
+  --deploy               deploy after writing without asking`,
+
+  deploy: `deploy — deploy the AWS stack
+
+  --seed
   --deploy-env <path>
   --home
-  --dry-run              print the command; invoke nothing
+  --dry-run`,
+
+  diff: `diff — cdk diff with the same context as deploy
+
+  --seed
+  --deploy-env <path>
+  --home
+  --dry-run`,
+
+  synth: `synth — cdk synth with the same context as deploy
+
+  --seed
+  --deploy-env <path>
+  --home
+  --dry-run`,
+
+  list: `list — list Context101 CloudFormation stacks (no checkout)
 
-list:
   --aws-profile <name>
   --aws-access-key-id
-  --aws-secret-access-key
+  --aws-secret-access-key`,
 
-destroy <StackName>:
-  --yes, -y              skip the confirmation prompt
+  destroy: `destroy <name> — tear down a listed stack (clones if needed)
+
+  --yes, -y
   --aws-profile <name>
   --aws-access-key-id
   --aws-secret-access-key
+  --dir <path>
   --deploy-env <path>
   --home
-  --dry-run              print the plan; destroy nothing
+  --dry-run`,
+
+  config: `config — show deploy-env keys (values redacted)
 
-config:
   --deploy-env <path>
-  --home
+  --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
+  "config set": `config set KEY=value — write one key (chmod 600; value is not printed)
 
-npx context101 (unscoped) downloads Context7's MCP from npm — unrelated.
-The publishable CLI is context101-cli; the bin name is context101.
-`.trim();
+  --deploy-env <path>
+  --home`,
+
+  help: `help [command] — list commands, or flags for one command`,
+};
 
 const INIT_ONLY = new Set([
   "--yes",
@@ -101,6 +107,7 @@ const INIT_ONLY = new Set([
 const DESTROY_FROM_INIT = new Set([
   "--yes",
   "-y",
+  "--dir",
   "--aws-profile",
   "--aws-access-key-id",
   "--aws-secret-access-key",
@@ -125,10 +132,22 @@ const COMMANDS = {
   remove: "destroy",
   rm: "destroy",
   config: "config",
+  help: "help",
 };
 
-export function helpText() {
-  return FLAG_HELP;
+export function helpText(topic) {
+  if (topic) {
+    const key = COMMANDS[topic] ?? topic;
+    return TOPIC_HELP[key] ?? helpText();
+  }
+  const nameW = Math.max(...COMMAND_LINES.map(([name]) => name.length));
+  return [
+    "Usage: context101 <command>",
+    "",
+    ...COMMAND_LINES.map(([name, desc]) => `  ${name.padEnd(nameW)}  ${desc}`),
+    "",
+    "npx context101 (unscoped) is Context7's MCP — use context101-cli.",
+  ].join("\n");
 }
 
 export function parseArgs(argv) {
@@ -157,24 +176,30 @@ export function parseArgs(argv) {
     configAction: "show",
     configKey: null,
     configValue: null,
+    helpTopic: null,
   };
 
   const args = [...argv];
   if (args.length === 0) return opts;
 
   const first = args[0];
-  if (COMMANDS[first]) {
+  if (first === "--help" || first === "-h") {
+    opts.command = "help";
+    opts.help = true;
+    args.shift();
+  } else 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 === "help") {
+    return parseHelpArgs(opts, args);
+  }
+
   if (opts.command === "config" && args[0] === "set") {
     args.shift();
     const pair = args.shift();
@@ -283,6 +308,33 @@ export function parseArgs(argv) {
   return opts;
 }
 
+function parseHelpArgs(opts, args) {
+  opts.help = true;
+  if (args[0] && !args[0].startsWith("-")) {
+    const topic = args.shift();
+    if (topic === "config" && args[0] === "set") {
+      args.shift();
+      opts.helpTopic = "config set";
+    } else if (COMMANDS[topic] && topic !== "help") {
+      opts.helpTopic = COMMANDS[topic];
+    } else if (topic === "help") {
+      opts.helpTopic = "help";
+    } else {
+      const err = new Error(`unknown command: ${topic}`);
+      err.code = "USAGE";
+      throw err;
+    }
+  }
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === "--help" || arg === "-h") continue;
+    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;

package/src/plan.js

@@ -83,29 +83,5 @@ function bootstrapLabel(plan) {
 }
 
 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");
+  return deployCommand(plan.seed);
 }

package/src/prompt.js

@@ -6,12 +6,24 @@ import {
 import { inferDriver, inferPrepare } from "./env-file.js";
 import { normalizeRepoUrl } from "./repo.js";
 
+export function deployNowMessage({ createRds = false } = {}) {
+  return createRds
+    ? "Deploy the stack now? (CDK + Docker; creates RDS)"
+    : "Deploy the stack now?";
+}
+
+export async function promptDeployNow(details = {}) {
+  const { confirm } = await import("@inquirer/prompts");
+  return confirm({
+    message: deployNowMessage(details),
+    default: false,
+  });
+}
+
 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("This writes a local secrets file. Press ^C to quit.");
   io.write("");
 
   const region = await input({

package/src/stacks.js

@@ -1,7 +1,7 @@
 import { DEPLOY_CLI, DESTROY_CLI, LIST_CLI, SMOOTH_REGION } from "./defaults.js";
 import { runCdk } from "./cdk-invoke.js";
+import { ensureRepoRoot } from "./clone.js";
 import { createExec } from "./exec.js";
-import { findRepoRoot } from "./repo.js";
 import { banner, writers } from "./style.js";
 
 export function parseStackSummaries(payload) {
@@ -70,12 +70,6 @@ export async function runList(opts, ctx) {
 
   banner(ctx);
 
-  const repoRoot = findRepoRoot(ctx.cwd);
-  if (!repoRoot) {
-    io.err("run this from a Context101 checkout (needs cdk/ and web/).");
-    return 1;
-  }
-
   const env = withAwsAuth(ctx.env ?? {}, {
     profile: opts.awsProfile,
     accessKeyId: opts.awsAccessKeyId,
@@ -101,12 +95,6 @@ export async function runDestroy(opts, ctx) {
     io.write("");
   }
 
-  const repoRoot = findRepoRoot(ctx.cwd);
-  if (!repoRoot) {
-    io.err("run this from a Context101 checkout (needs cdk/ and web/).");
-    return 1;
-  }
-
   const stackName = String(opts.stackName || "").trim();
   if (!stackName) {
     io.err(`destroy needs a stack name from \`${LIST_CLI}\`.`);
@@ -157,6 +145,25 @@ export async function runDestroy(opts, ctx) {
   io.warn(
     "Non-default brains are not in CloudFormation — delete them from /brains first."
   );
+
+  const checkout = ensureRepoRoot({
+    cwd: ctx.cwd,
+    dir: opts.dir,
+    exec,
+    io,
+    preferHomeClone: true,
+    homeDir: ctx.homeDir,
+  });
+  if (checkout.error) {
+    io.err(checkout.error);
+    return 1;
+  }
+  const repoRoot = checkout.repoRoot;
+  if (!repoRoot) {
+    io.err("could not find or clone a Context101 checkout (needs cdk/ and web/).");
+    return 1;
+  }
+
   io.write(`Destroying ${stackName}…`);
   return (ctx.runDeploy ?? runCdk)({
     repoRoot,