@oaklandzoo/ostup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# ostup
+
+Scaffold a new client project with one command. Get a live GitHub repo
+and live Vercel deploy URL in under five minutes.
+
+## What this does
+
+When you run this tool, it will:
+
+1. Ask you a few questions about the project
+2. Create a folder on your machine with a Next.js starter site
+3. Create a private GitHub repository for the project
+4. Deploy the site to Vercel and give you a live URL
+5. Set up institutional memory files (CLAUDE.md, AGENTS.md) so any CLI
+   agent (Claude Code, Codex, Gemini CLI) knows your project rules
+6. Create an `inputs/` folder inside the project where you can drop any
+   prior materials (research, reference repos, screenshots, brand
+   assets) you want the agent to have on hand
+
+## What you need before running it
+
+### One-time machine setup (you only do this once)
+
+1. Install Node.js 20 or higher. Download from https://nodejs.org
+
+2. Install GitHub CLI. In Terminal:
+   ```
+   brew install gh
+   ```
+   Then log in:
+   ```
+   gh auth login
+   ```
+   Choose: GitHub.com, then HTTPS, then "Login with a web browser."
+   Follow the prompts.
+
+3. Install Vercel CLI. In Terminal:
+   ```
+   npm install -g vercel
+   ```
+   Then log in:
+   ```
+   vercel login
+   ```
+   Choose your email login method.
+
+### Accounts you need
+
+- GitHub account: free at https://github.com/signup
+- Vercel account: free at https://vercel.com/signup (sign in with GitHub)
+
+If you do not have these accounts, the tool will pause and walk you
+through creating them when you reach that step.
+
+## Install
+
+Two paths. Pick the one that matches how you got ostup.
+
+### Path A: from npm (after `ostup` is published)
+
+```
+npx ostup init
+```
+
+That is the whole install. `npx` downloads ostup on first run.
+
+As of right now, `ostup` is not yet published to npm. Use Path B below.
+
+### Path B: from source (today's path)
+
+If you cloned or downloaded https://github.com/DubsFan/goodshin:
+
+```
+cd /path/to/goodshin/ostup
+npm install     # downloads ostup's own dependencies
+npm link        # adds `ostup` to your PATH globally
+ostup --version # should print 0.1.0
+```
+
+After `npm link` you can run `ostup` from any folder. You only do this
+once per machine.
+
+## Use
+
+In Terminal, navigate to the parent folder where you want the new
+project to be created:
+
+```
+cd ~/Projects
+```
+
+Then run:
+
+```
+ostup init
+```
+
+The tool will ask you a series of questions. Answer each one. When the
+tool finishes, you will see a live deploy URL. Open it in your browser
+to confirm the site is up.
+
+## Questions the tool will ask
+
+| Question | What to answer |
+|---|---|
+| Project name | A short kebab-case name like `client-name` or `widget-shop` |
+| Display name | The human readable version, like "Client Name" |
+| Description | One sentence, 10 to 200 characters |
+| Profile | Press Enter to accept `goodshin` |
+| Stack | Press Enter to accept `next` (Next.js) |
+| Visibility | Press Enter to accept `private` |
+| GitHub owner | Press Enter to accept your GitHub username |
+| Vercel scope | Press Enter to accept your Vercel scope |
+| Prior materials? | Answer y if you have a folder of research, reference repos, images, etc. to bring in. Tool will ask for a path and copy them into `inputs/`. Answer n to skip; you can drop files into `inputs/` later. |
+
+If the tool detects you are not logged in to GitHub or Vercel, it will
+print step-by-step instructions and pause until you finish.
+
+## What you get when it finishes
+
+- A local folder at `./<project-name>` with the Next.js site code
+- A private repo at `https://github.com/<your-username>/<project-name>`
+- A live deploy at a `*.vercel.app` URL
+- CLAUDE.md, AGENTS.md, README.md inside the project, filled in with
+  your project details
+- An `inputs/` folder for any operator-supplied materials, with a
+  README explaining what goes where
+
+## What to do next
+
+Open the new folder in your editor and start working. To use a CLI
+agent:
+```
+cd <project-name>
+claude
+```
+Or replace `claude` with `codex`, `gemini`, or your preferred agent.
+The CLAUDE.md and AGENTS.md files tell the agent your conventions so
+you do not have to repeat them every session.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| "node: command not found" | Install Node 20+ from https://nodejs.org |
+| "gh: command not found" | Run `brew install gh` |
+| "vercel: command not found" | Run `npm install -g vercel` |
+| "gh auth required" | Run `gh auth login` |
+| "vercel auth required" | Run `vercel login` |
+| "Project name invalid" | Use only lowercase letters, numbers, and hyphens |
+| "Repo already exists" | Pick a different project name |
+| Vercel deploy hangs more than 5 minutes | Cancel with Ctrl-C, run again |
+| Deploy URL returns 401 | The tool tried to auto-disable Vercel deployment protection but could not. Open Vercel dashboard, find your project, Settings, Deployment Protection, Disable. |
+| "ingest path not found" | The path you gave does not exist. Re-run and provide a valid absolute or relative path. |
+
+## Advanced: API tokens instead of interactive login
+
+If you want to use API tokens (for CI, automation, or to avoid the
+browser login flow), copy `.env.example` to `.env` and fill in your
+tokens. The tool reads credentials in this order:
+
+1. Environment variables (`GH_TOKEN`, `VERCEL_TOKEN`)
+2. `.env` file in the current directory
+3. Interactive CLI auth from `gh` and `vercel`
+
+Any one of those is enough. Never commit your `.env` to git.
+
+For full automation including automatic disable of Vercel deployment
+protection on team accounts, set `VERCEL_TOKEN` in your environment or
+`.env`. Without it, the tool falls back to reading the Vercel CLI auth
+file on macOS at `~/Library/Application Support/com.vercel.cli/auth.json`.
+On a fresh machine where you have not run `vercel login` yet, that file
+will not exist, so `VERCEL_TOKEN` is the reliable path. Get a token at
+https://vercel.com/account/tokens.
+
+## Advanced: bring materials in non-interactively
+
+Pass `--ingest <path>` to copy a folder of operator-supplied materials
+into the new project's `inputs/` folder without being prompted:
+
+```
+npx ostup init --yes --name my-app --ingest ~/Desktop/client-handoff
+```
+
+The tool recursively copies the contents and writes
+`inputs/INGEST_MANIFEST.md` listing what was brought in.
+
+## Support
+
+This tool is maintained at https://github.com/DubsFan/goodshin
+Open an issue there if you hit a bug or need help.

package/bin/cli.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// cli.mjs: parse argv, load .env, dispatch to a subcommand (init | update).
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDotEnv } from '../src/env-loader.mjs';
+import { setDryRun } from '../src/exec.mjs';
+
+loadDotEnv();
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const SUBCOMMANDS = new Set(['init', 'update']);
+
+async function readPkg() {
+  const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
+  return JSON.parse(raw);
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--yes' || a === '-y') flags.yes = true;
+    else if (a === '--force') flags.force = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--update') flags.update = true;
+    else if (a === '--kit-only') flags.kitOnly = true;
+    else if (a === '--version' || a === '-v') flags.version = true;
+    else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--profile') flags.profile = argv[++i];
+    else if (a.startsWith('--profile=')) flags.profile = a.slice('--profile='.length);
+    else if (a === '--name') flags.name = argv[++i];
+    else if (a.startsWith('--name=')) flags.name = a.slice('--name='.length);
+    else if (a === '--config') flags.config = argv[++i];
+    else if (a.startsWith('--config=')) flags.config = a.slice('--config='.length);
+    else if (a === '--ingest') flags.ingest = argv[++i];
+    else if (a.startsWith('--ingest=')) flags.ingest = a.slice('--ingest='.length);
+    else if (a.startsWith('-')) {
+      process.stderr.write(`unknown flag: ${a}\n`);
+      process.exit(1);
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'ostup: scaffold a new repo with the Ostup Agent Kit plus GitHub and Vercel.',
+      '',
+      'Usage:',
+      '  ostup <command> [flags]',
+      '',
+      'Commands:',
+      '  init                Scaffold a new project (interactive or with --yes).',
+      '  update              Refresh bundled templates from the pinned source.',
+      '',
+      'Flags for `ostup init`:',
+      '  --yes, -y           Accept defaults. Still prompts where no default exists.',
+      '  --force             Allow scaffolding into a non-empty target dir.',
+      '  --dry-run           Print every action without running any subprocess.',
+      '  --profile <name>    Skip the profile prompt (goodshin or default).',
+      '  --name <kebab>      Skip the projectName prompt.',
+      '  --ingest <path>     Copy operator materials from <path> into inputs/.',
+      '  --kit-only          Drop the markdown kit into a target dir, no GitHub or Vercel.',
+      '  --config <path>     Read .ostup-config.yml from this path (kit-only mode).',
+      '',
+      'Global flags:',
+      '  --version, -v       Print version and exit.',
+      '  --help, -h          Print this help and exit.',
+      '',
+    ].join('\n')
+  );
+}
+
+const { flags, positional } = parseArgs(process.argv.slice(2));
+
+if (flags.dryRun) setDryRun(true);
+
+if (flags.version) {
+  const pkg = await readPkg();
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+if (flags.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const subcommand = flags.update ? 'update' : (positional[0] || null);
+
+if (!subcommand) {
+  printHelp();
+  process.exit(0);
+}
+
+if (!SUBCOMMANDS.has(subcommand)) {
+  process.stderr.write(`unknown subcommand: ${subcommand}\nRun "ostup --help" for usage.\n`);
+  process.exit(1);
+}
+
+const subPositional = flags.update ? positional : positional.slice(1);
+
+if (subcommand === 'update') {
+  const { update } = await import('../src/update.mjs');
+  try {
+    await update();
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set(['CONFIG_NOT_FOUND', 'UPDATE_NOT_CONFIGURED']);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
+// subcommand === 'init'
+if (flags.kitOnly) {
+  const { scaffold } = await import('../src/scaffold.mjs');
+  const targetDir = subPositional[0] || process.cwd();
+  try {
+    await scaffold({ targetDir, flags });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set(['TARGET_NOT_EMPTY', 'CONFIG_NOT_FOUND', 'NO_TTY']);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
+const { runMvp } = await import('../src/mvp-flow.mjs');
+try {
+  await runMvp({ flags });
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  const userErrors = new Set([
+    'NO_TTY',
+    'USER_ABORT',
+    'TARGET_NOT_EMPTY',
+    'NO_GH_CREDS',
+    'NO_VERCEL_CREDS',
+    'INGEST_PATH_NOT_FOUND',
+  ]);
+  process.exit(userErrors.has(err.code) ? 1 : 2);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@oaklandzoo/ostup",
+  "version": "0.1.0",
+  "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
+  "type": "module",
+  "bin": {
+    "ostup": "bin/cli.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.mjs'",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "GG",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DubsFan/goodshin.git",
+    "directory": "ostup"
+  },
+  "homepage": "https://github.com/DubsFan/goodshin#readme",
+  "bugs": {
+    "url": "https://github.com/DubsFan/goodshin/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "scaffold",
+    "agent",
+    "template",
+    "init",
+    "starter",
+    "prd",
+    "nextjs",
+    "vercel"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "execa": "^9.6.1",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2",
+    "yaml": "^2.9.0"
+  }
+}

package/src/config.mjs

@@ -0,0 +1,41 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export async function loadConfig({ targetDir, configPath }) {
+  const path = configPath
+    ? resolve(configPath)
+    : resolve(targetDir, '.ostup-config.yml');
+
+  if (!existsSync(path)) {
+    if (configPath) {
+      const err = new Error(`config file not found: ${path}`);
+      err.code = 'CONFIG_NOT_FOUND';
+      throw err;
+    }
+    return {};
+  }
+
+  const raw = await readFile(path, 'utf8');
+  const parsed = parseYaml(raw);
+  if (parsed == null || typeof parsed !== 'object') return {};
+  return parsed;
+}
+
+export function mergeValues({ config, prompts, defaults }) {
+  return {
+    projectName: pick('projectName', config, prompts, defaults),
+    purpose:     pick('purpose',     config, prompts, defaults),
+    owner:       pick('owner',       config, prompts, defaults),
+    stack:       pick('stack',       config, prompts, defaults),
+    deploy:      pick('deploy',      config, prompts, defaults),
+  };
+}
+
+function pick(key, ...sources) {
+  for (const src of sources) {
+    if (src && src[key] != null && src[key] !== '') return src[key];
+  }
+  return undefined;
+}

package/src/credential-prompts.mjs

@@ -0,0 +1,117 @@
+// credential-prompts.mjs: detect GitHub and Vercel credentials, prompt and persist only if missing.
+import * as p from '@clack/prompts';
+import { execSync } from 'node:child_process';
+
+export function checkGithubAuth({ env = process.env, runner = defaultCmdOk } = {}) {
+  if (env.GH_TOKEN) return { ok: true, source: 'env-or-dotenv' };
+  if (runner('gh auth status')) return { ok: true, source: 'gh-cli' };
+  return { ok: false };
+}
+
+export function checkVercelAuth({ env = process.env, runner = defaultCmdOk } = {}) {
+  if (env.VERCEL_TOKEN) return { ok: true, source: 'env-or-dotenv' };
+  if (runner('vercel whoami')) return { ok: true, source: 'vercel-cli' };
+  return { ok: false };
+}
+
+function defaultCmdOk(cmd) {
+  try {
+    execSync(cmd, { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const GH_BLURB = [
+  '',
+  'GitHub credentials not found.',
+  '',
+  'If you do not have a GitHub account yet:',
+  '  1. Open https://github.com/signup',
+  '  2. Create an account, then return here.',
+  '',
+  'To create a Personal Access Token:',
+  '  1. Open https://github.com/settings/personal-access-tokens',
+  '  2. Click Generate new token (fine-grained).',
+  '  3. Name: ostup-init',
+  '  4. Resource owner: your username',
+  '  5. Repository access: All repositories',
+  '  6. Permissions:',
+  '     - Administration: Read and write',
+  '     - Contents: Read and write',
+  '     - Metadata: Read',
+  '  7. Generate token, copy the value.',
+  '',
+].join('\n');
+
+const VERCEL_BLURB = [
+  '',
+  'Vercel credentials not found.',
+  '',
+  'If you do not have a Vercel account yet:',
+  '  1. Open https://vercel.com/signup',
+  '  2. Create an account, then return here.',
+  '',
+  'To create a Personal Access Token:',
+  '  1. Open https://vercel.com/account/tokens',
+  '  2. Click Create Token.',
+  '  3. Name: ostup-init',
+  '  4. Scope: Full Account (default for personal tokens).',
+  '  5. Create, copy the value.',
+  '',
+].join('\n');
+
+export async function promptForGithubToken() {
+  process.stdout.write(GH_BLURB);
+  const token = await p.password({
+    message: 'Paste your GitHub Personal Access Token (leave blank to skip)',
+  });
+  if (p.isCancel(token)) return null;
+  return typeof token === 'string' && token.trim() ? token.trim() : null;
+}
+
+export async function promptForVercelToken() {
+  process.stdout.write(VERCEL_BLURB);
+  const token = await p.password({
+    message: 'Paste your Vercel Personal Access Token (leave blank to skip)',
+  });
+  if (p.isCancel(token)) return null;
+  return typeof token === 'string' && token.trim() ? token.trim() : null;
+}
+
+export async function ensureCredentials({ stack = 'next' } = {}) {
+  const collected = {};
+
+  const gh = checkGithubAuth();
+  if (gh.ok) {
+    process.stdout.write(`GitHub: using existing auth (${gh.source}).\n`);
+  } else {
+    const token = await promptForGithubToken();
+    if (!token) {
+      const err = new Error('GitHub credentials are required.');
+      err.code = 'NO_GH_CREDS';
+      throw err;
+    }
+    process.env.GH_TOKEN = token;
+    collected.GH_TOKEN = token;
+  }
+
+  if (stack !== 'none') {
+    const v = checkVercelAuth();
+    if (v.ok) {
+      process.stdout.write(`Vercel: using existing auth (${v.source}).\n`);
+    } else {
+      const token = await promptForVercelToken();
+      if (!token) {
+        const err = new Error('Vercel credentials are required for stack=' + stack + '.');
+        err.code = 'NO_VERCEL_CREDS';
+        throw err;
+      }
+      process.env.VERCEL_TOKEN = token;
+      collected.VERCEL_TOKEN = token;
+    }
+  }
+
+  return { collected };
+}

package/src/env-loader.mjs

@@ -0,0 +1,27 @@
+// env-loader.mjs: load .env from cwd into process.env without overwriting existing keys.
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export function loadDotEnv(dir = process.cwd()) {
+  const path = resolve(dir, '.env');
+  const parsed = {};
+  if (!existsSync(path)) return parsed;
+  const raw = readFileSync(path, 'utf8');
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    parsed[key] = value;
+    if (!(key in process.env)) process.env[key] = value;
+  }
+  return parsed;
+}

package/src/exec.mjs

@@ -0,0 +1,78 @@
+// exec.mjs: uniform shell call wrapper with logging, dry-run capture, and step-aware error formatting.
+import { execa } from 'execa';
+
+const HINTS = {
+  'gh repo create': 'Confirm the repo name is not already taken under this owner.',
+  'gh repo view': 'Verify the repo was created and you have access.',
+  'gh auth status': 'Run: gh auth login',
+  'vercel link': 'Confirm the Vercel scope exists and you have access.',
+  'vercel deploy': 'Run vercel logs <deployment-url> or rerun vercel manually to see the build error.',
+  'npx create-next-app': 'Check your internet connection and the create-next-app version compatibility.',
+  'git init': 'Confirm git is installed and you have write access to this directory.',
+  'git commit': 'Confirm git user.name and user.email are configured.',
+  'git push': 'Confirm you have push access to the remote.',
+};
+
+const defaultExeca = (cmd, args, opts) => execa(cmd, args, opts);
+
+let _runner = defaultExeca;
+let _dryRun = false;
+let _captured = [];
+let _quiet = false;
+
+export function setRunner(fn) {
+  _runner = fn || defaultExeca;
+}
+export function resetRunner() {
+  _runner = defaultExeca;
+}
+export function setDryRun(v) {
+  _dryRun = Boolean(v);
+  _captured = [];
+}
+export function isDryRun() {
+  return _dryRun;
+}
+export function getCaptured() {
+  return _captured.slice();
+}
+export function setQuiet(v) {
+  _quiet = Boolean(v);
+}
+
+function hintFor(cmd, args) {
+  const sig = `${cmd} ${(args || []).slice(0, 2).join(' ')}`.trim();
+  for (const key of Object.keys(HINTS)) {
+    if (sig.startsWith(key)) return HINTS[key];
+  }
+  return 'See the command stderr above.';
+}
+
+export async function run(step, cmd, args = [], opts = {}) {
+  const display = `${cmd} ${args.join(' ')}`.trim();
+  if (_dryRun) {
+    _captured.push({ step, cmd, args, opts });
+    if (!_quiet) process.stdout.write(`[${step}] would run: ${display}\n`);
+    return { stdout: '', stderr: '', exitCode: 0, dryRun: true };
+  }
+  if (!_quiet) process.stdout.write(`[${step}] start: ${display}\n`);
+  try {
+    return await _runner(cmd, args, { ...opts });
+  } catch (err) {
+    const stderr = (err && (err.stderr || err.shortMessage || err.message) || '').toString().trim();
+    process.stderr.write(
+      [
+        `[${step}] FAIL`,
+        `  Command: ${display}`,
+        `  Stderr:  ${stderr || '(empty)'}`,
+        `  Fix:     ${hintFor(cmd, args)}`,
+        'Exit 1.',
+      ].join('\n') + '\n'
+    );
+    const e = new Error(`step ${step} failed`);
+    e.code = 'STEP_FAILED';
+    e.step = step;
+    e.cause = err;
+    throw e;
+  }
+}