context101-cli 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context101-cli",
-  "version": "0.1.1",
+  "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/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,85 +1,90 @@
 import { DRIVER_NEON, DRIVER_POSTGRES } from "./defaults.js";
 
-const FLAG_HELP = `
-Usage: context101 <command> [options]
-
-  init                 write a local secrets file (default); TTY asks to deploy
-  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
+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);
-                         does not deploy unless --deploy is also passed
+                         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 without asking
-
-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",
@@ -102,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",
@@ -126,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) {
@@ -158,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();
@@ -284,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/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,