komplian 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# komplian (npm CLI)
+
+**Developers:** from any machine with Node 18+ and GitHub CLI (`gh`):
+
+```bash
+npx komplian onboard --yes
+```
+
+This downloads the CLI from npm (no manual git clone), opens GitHub login if needed, and clones the repos your account can access (filtered by team in the bundled `komplian-team-repos.json`). Default workspace: `~/komplian` (Windows: `%USERPROFILE%\komplian`).
+
+**Maintainers:** publish **from this folder** (the one that contains `package.json` — not the monorepo root):
+
+```bash
+cd path/to/monorepo/scripts   # e.g. cd ~/Desktop/temp/scripts
+npm login                     # once per machine
+npm publish --access public
+```
+
+Running `npm publish` from the repo root causes `ENOENT package.json` because the npm package lives only under `scripts/`.
+
+Bump `version` in `package.json` before each publish.
+
+**If publish fails with `403` / “Two-factor authentication … required”:** enable **2FA** on your npm account (*npmjs.com → Account → Security*), then run `npm publish` again (npm may prompt for an OTP). For CI, create a **granular access token** (*Access Tokens → Granular token*) with **Publish** on the `komplian` package and “**Bypass two-factor authentication**” if your org allows it; set `NPM_TOKEN` in GitHub Actions.

package/komplian-onboard.mjs

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+/**
+ * Komplian onboard — one-command dev setup (GitHub CLI auth + clone + optional npm install).
+ * Zero npm deps: Node 18+, git, gh, and komplian-team-repos.json beside this file.
+ *
+ * Usage:
+ *   npx komplian onboard --yes   # npm ships this package; no manual monorepo clone for developers
+ *
+ * Security: `gh` OAuth; active org membership verified via GitHub API before clones; repo ACLs enforced by GitHub. See ONBOARDING.md.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, mkdirSync, cpSync, rmSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const c = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+};
+
+function log(s = "") {
+  console.log(s);
+}
+
+function banner() {
+  // Block Unicode (cfonts "block"). Fourth letter is P: row 4 uses ██╔═══╝; R would use ██╔══██╗.
+  log(
+    [
+      `${c.cyan}${c.bold}`,
+      "██╗  ██╗  ██████╗  ███╗   ███╗ ██████╗  ██╗      ██╗  █████╗  ███╗   ██╗",
+      "██║ ██╔╝ ██╔═══██╗ ████╗ ████║ ██╔══██╗ ██║      ██║ ██╔══██╗ ████╗  ██║",
+      "█████╔╝  ██║   ██║ ██╔████╔██║ ██████╔╝ ██║      ██║ ███████║ ██╔██╗ ██║",
+      "██╔═██╗  ██║   ██║ ██║╚██╔╝██║ ██╔═══╝  ██║      ██║ ██╔══██║ ██║╚██╗██║",
+      "██║  ██╗ ╚██████╔╝ ██║ ╚═╝ ██║ ██║      ███████╗ ██║ ██║  ██║ ██║ ╚████║",
+      "╚═╝  ╚═╝  ╚═════╝  ╚═╝     ╚═╝ ╚═╝      ╚══════╝ ╚═╝ ╚═╝  ╚═╝ ╚═╝  ╚═══╝",
+      `${c.reset}`,
+      `${c.dim}  Secure setup · GitHub CLI · HTTPS clones · No secrets stored by this CLI${c.reset}`,
+      "",
+    ].join("\n")
+  );
+}
+
+function ghOk() {
+  const r = spawnSync("gh", ["auth", "status", "-h", "github.com"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return r.status === 0;
+}
+
+/** Scopes: repo (clone), read:org (verify org membership — required for private orgs). */
+function runGhAuth() {
+  log(
+    `${c.yellow}→${c.reset} Opening ${c.bold}GitHub${c.reset} login in the browser (OAuth). We never see your password.`
+  );
+  const r = spawnSync(
+    "gh",
+    ["auth", "login", "-h", "github.com", "-s", "repo", "-s", "read:org", "-w"],
+    { stdio: "inherit" }
+  );
+  return r.status === 0;
+}
+
+function ghApiJson(path) {
+  const r = spawnSync("gh", ["api", path], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return { status: r.status, stdout: r.stdout || "", stderr: r.stderr || "" };
+}
+
+/**
+ * Ensures the authenticated user is an active member of the GitHub org (not just any GitHub account).
+ * Relies on GitHub as source of truth; optional SAML/SSO is enforced by the org on github.com.
+ */
+function verifyOrgMembership(org) {
+  const enc = encodeURIComponent(org);
+  const mem = ghApiJson(`user/memberships/orgs/${enc}`);
+  if (mem.status === 200) {
+    try {
+      const j = JSON.parse(mem.stdout);
+      if (j.state === "active") {
+        return;
+      }
+      log(
+        `${c.red}✗${c.reset} Organization ${c.bold}${org}${c.reset} membership is not active (state: ${j.state || "?"}).`
+      );
+      process.exit(1);
+    } catch {
+      log(`${c.red}✗${c.reset} Invalid response verifying org membership.`);
+      process.exit(1);
+    }
+  }
+  if (mem.status === 404) {
+    log(
+      `${c.red}✗${c.reset} This GitHub account is ${c.bold}not a member${c.reset} of org ${c.bold}${org}${c.reset}.`
+    );
+    log(
+      `${c.dim}  Only invited org members can run this tool. Wrong account? Run: gh auth logout && gh auth login${c.reset}`
+    );
+    process.exit(1);
+  }
+  const hint = (mem.stderr + mem.stdout).toLowerCase();
+  if (mem.status === 403 || hint.includes("read:org") || hint.includes("scope")) {
+    log(`${c.red}✗${c.reset} Token cannot verify org membership (needs ${c.bold}read:org${c.reset} scope).`);
+    log(
+      `${c.dim}  Run: gh auth refresh -h github.com -s repo -s read:org${c.reset}`
+    );
+    process.exit(1);
+  }
+  log(
+    `${c.red}✗${c.reset} Could not verify org membership (${mem.status}):\n${c.dim}${(mem.stderr || mem.stdout).trim()}${c.reset}`
+  );
+  process.exit(1);
+}
+
+function logGhIdentity() {
+  const u = ghApiJson("user");
+  if (u.status !== 200) return;
+  try {
+    const j = JSON.parse(u.stdout);
+    if (j.login) {
+      log(`${c.dim}  Signed in as ${c.bold}@${j.login}${c.reset}${c.dim} (github.com)${c.reset}`);
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+function needCmd(name) {
+  const r = spawnSync("command", ["-v", name], { shell: true, stdio: "ignore" });
+  if (r.status !== 0) {
+    log(`${c.red}✗${c.reset} Missing ${c.bold}${name}${c.reset}. Install it and retry.`);
+    process.exit(1);
+  }
+}
+
+function loadConfig(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function ghRepoList(org) {
+  const r = spawnSync(
+    "gh",
+    ["repo", "list", org, "--limit", "1000", "--json", "name,isArchived,isFork"],
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  if (r.status !== 0) {
+    log(`${c.red}✗${c.reset} gh repo list failed:\n${r.stderr || r.stdout}`);
+    process.exit(1);
+  }
+  const rows = JSON.parse(r.stdout || "[]");
+  const names = new Set();
+  for (const row of rows) {
+    if (row.isArchived || row.isFork) continue;
+    names.add(row.name);
+  }
+  return names;
+}
+
+function resolveRepos(cfg, org, teamArg, allRepos) {
+  const exclude = new Set(cfg.exclude_from_all || []);
+  const visible = ghRepoList(org);
+
+  if (allRepos) {
+    return [...visible].filter((n) => !exclude.has(n)).sort();
+  }
+
+  let team = (teamArg || "").trim();
+  if (!team) team = (cfg.default_team || "").trim();
+
+  if (!team) {
+    return [...visible].sort();
+  }
+
+  const teams = cfg.teams || {};
+  if (!teams[team]) {
+    log(
+      `${c.red}✗${c.reset} Unknown team ${c.bold}${team}${c.reset}. Valid: ${Object.keys(teams).sort().join(", ")}`
+    );
+    process.exit(2);
+  }
+
+  const allowed = teams[team];
+  const out = [];
+  for (const name of [...allowed].sort()) {
+    if (!visible.has(name)) {
+      log(`${c.dim}○ skip ${org}/${name} (no access or not in org)${c.reset}`);
+      continue;
+    }
+    out.push(name);
+  }
+  return out;
+}
+
+function isSafeTargetDir(abs) {
+  const n = normalize(abs);
+  const bad = ["/", "/root", "/etc", "/usr", "/bin", "/System", "/Library"];
+  return !bad.includes(n);
+}
+
+function cloudLine(org, name, status) {
+  const cloud = `${c.blue}☁${c.reset}`;
+  if (status === "ok") {
+    return `  ${cloud}  ${c.green}✓${c.reset} ${c.bold}${org}/${name}${c.reset} ${c.dim}cloned${c.reset}`;
+  }
+  if (status === "skip") {
+    return `  ${cloud}  ${c.yellow}○${c.reset} ${org}/${name} ${c.dim}(already there)${c.reset}`;
+  }
+  if (status === "fail") {
+    return `  ${cloud}  ${c.red}✗${c.reset} ${org}/${name} ${c.dim}failed${c.reset}`;
+  }
+  return `  ${cloud}  ${c.cyan}…${c.reset} ${org}/${name} ${c.dim}cloning…${c.reset}`;
+}
+
+function cloneOne(org, name, workspace, useSsh) {
+  const gitDir = join(workspace, name, ".git");
+  if (existsSync(gitDir)) {
+    log(cloudLine(org, name, "skip"));
+    return true;
+  }
+  process.stdout.write(`\r${cloudLine(org, name, "pending")}`);
+  const args = useSsh
+    ? ["clone", `git@github.com:${org}/${name}.git`, name]
+    : ["repo", "clone", `${org}/${name}`, name];
+  const cmd = useSsh ? "git" : "gh";
+  const r = spawnSync(cmd, args, {
+    cwd: workspace,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  process.stdout.write("\r\x1b[K");
+  if (r.status === 0) {
+    log(cloudLine(org, name, "ok"));
+    return true;
+  }
+  log(cloudLine(org, name, "fail"));
+  if (r.stderr) log(`${c.dim}${r.stderr.trim()}${c.reset}`);
+  return false;
+}
+
+function copyCursorPack(workspace, cursorRepoUrl) {
+  const rootCursor = join(workspace, ".cursor");
+  if (cursorRepoUrl && String(cursorRepoUrl).trim()) {
+    const tmp = join(workspace, ".cursor-bootstrap-tmp");
+    rmSync(tmp, { recursive: true, force: true });
+    log(`${c.dim}→${c.reset} Shallow clone Cursor pack…`);
+    const r = spawnSync("git", ["clone", "--depth", "1", String(cursorRepoUrl).trim(), tmp], {
+      cwd: workspace,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+    if (r.status === 0 && existsSync(join(tmp, ".cursor"))) {
+      rmSync(rootCursor, { recursive: true, force: true });
+      cpSync(join(tmp, ".cursor"), rootCursor, { recursive: true });
+      rmSync(tmp, { recursive: true, force: true });
+      log(`${c.green}✓${c.reset} ${c.bold}.cursor${c.reset} ${c.dim}← KOMPLIAN_CURSOR_REPO${c.reset}`);
+      return;
+    }
+    rmSync(tmp, { recursive: true, force: true });
+    log(`${c.yellow}○${c.reset} KOMPLIAN_CURSOR_REPO clone failed or missing .cursor/ at repo root`);
+  }
+
+  const aiToolsCursor = join(workspace, "ai-tools", ".cursor");
+  if (existsSync(aiToolsCursor)) {
+    rmSync(rootCursor, { recursive: true, force: true });
+    cpSync(aiToolsCursor, rootCursor, { recursive: true });
+    log(`${c.green}✓${c.reset} ${c.bold}.cursor${c.reset} ${c.dim}← ai-tools${c.reset}`);
+    return;
+  }
+  log(
+    `${c.dim}○ No workspace .cursor/ (add ai-tools to your team or set KOMPLIAN_CURSOR_REPO).${c.reset}`
+  );
+}
+
+function npmInstallEach(workspace) {
+  log("");
+  log(`${c.cyan}━━ npm install per repo ━━${c.reset}`);
+  for (const ent of readdirSync(workspace)) {
+    const d = join(workspace, ent);
+    if (!statSync(d).isDirectory()) continue;
+    const pkg = join(d, "package.json");
+    if (!existsSync(pkg)) continue;
+    log(`${c.dim}→${c.reset} ${ent}`);
+    const r = spawnSync("npm", ["install"], { cwd: d, stdio: "inherit" });
+    if (r.status !== 0) {
+      log(`${c.yellow}○${c.reset} npm install had issues in ${ent}`);
+    } else {
+      log(`${c.green}✓${c.reset} ${ent}`);
+    }
+  }
+}
+
+function usage() {
+  log(`Usage: komplian onboard [options] [dir]`);
+  log(`  npx komplian onboard --yes        clones + npm install (default dir: ~/komplian)`);
+  log(``);
+  log(`  Subcommand onboard implies --install; add --no-install to skip npm install.`);
+  log(`  -y, --yes          Non-interactive (default team from JSON)`);
+  log(`  -t, --team <slug>  Team from komplian-team-repos.json`);
+  log(`  -i, --install      npm install (on by default with onboard; optional without subcommand)`);
+  log(`  --no-install       Skip npm install (only after onboard)`);
+  log(`  --all-repos        Clone all visible org repos (minus exclude list)`);
+  log(`  --ssh              Use SSH URLs (git@github.com:...)`);
+  log(`  --list-teams       Print team slugs and exit`);
+  log(`  -h, --help         This help`);
+}
+
+function parseArgs(argv) {
+  const out = {
+    yes: false,
+    install: false,
+    noInstall: false,
+    allRepos: false,
+    ssh: false,
+    listTeams: false,
+    help: false,
+    team: "",
+    workspace: "",
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--no-install") out.noInstall = true;
+    else if (a === "-i" || a === "--install") out.install = true;
+    else if (a === "--all-repos") out.allRepos = true;
+    else if (a === "--ssh") out.ssh = true;
+    else if (a === "--list-teams") out.listTeams = true;
+    else if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "-t" || a === "--team") {
+      out.team = argv[++i] || "";
+    } else if (a.startsWith("-")) {
+      log(`${c.red}✗${c.reset} Unknown option: ${a}`);
+      usage();
+      process.exit(1);
+    } else rest.push(a);
+  }
+  if (rest[0]) out.workspace = rest[0];
+  return out;
+}
+
+async function pickTeam(cfg) {
+  const teams = Object.keys(cfg.teams || {}).sort();
+  const def = (cfg.default_team || "").trim();
+  log(`${c.cyan}Teams:${c.reset}`);
+  teams.forEach((t, i) => {
+    const mark = t === def ? ` ${c.dim}(default)${c.reset}` : "";
+    log(`  ${i + 1}. ${t}${mark}`);
+  });
+  const rl = createInterface({ input, output });
+  const ans = await rl.question(
+    `\n${c.bold}Choose number or name${c.reset} [${def}]: `
+  );
+  rl.close();
+  const trimmed = (ans || "").trim();
+  if (!trimmed) return def;
+  const n = parseInt(trimmed, 10);
+  if (!Number.isNaN(n) && n >= 1 && n <= teams.length) return teams[n - 1];
+  if (teams.includes(trimmed)) return trimmed;
+  return def || teams[0] || "";
+}
+
+function normalizeArgv(argv) {
+  const a = [...argv];
+  let fromOnboardSubcommand = false;
+  if (a[0] === "onboard") {
+    a.shift();
+    fromOnboardSubcommand = true;
+  }
+  return { argv: a, fromOnboardSubcommand };
+}
+
+async function main() {
+  const configPath = join(__dirname, "komplian-team-repos.json");
+  const { argv, fromOnboardSubcommand } = normalizeArgv(process.argv.slice(2));
+  const args = parseArgs(argv);
+  if (fromOnboardSubcommand && !args.noInstall && !args.listTeams && !args.help) {
+    args.install = true;
+  }
+
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  if (args.listTeams) {
+    if (!existsSync(configPath)) {
+      log(`${c.red}✗${c.reset} Missing ${configPath}`);
+      process.exit(1);
+    }
+    needCmd("gh");
+    if (!ghOk()) {
+      log(`${c.red}✗${c.reset} Not logged in to GitHub. Run: ${c.bold}gh auth login -h github.com -s repo -s read:org -w${c.reset}`);
+      process.exit(1);
+    }
+    const cfg = loadConfig(configPath);
+    const orgList = process.env.KOMPLIAN_ORG || cfg.org || "Komplian";
+    verifyOrgMembership(orgList);
+    log(Object.keys(cfg.teams || {}).sort().join("\n"));
+    return;
+  }
+
+  if (!existsSync(configPath)) {
+    log(`${c.red}✗${c.reset} Missing config: ${configPath}`);
+    process.exit(1);
+  }
+
+  needCmd("git");
+  needCmd("gh");
+
+  const nodeMajor = Number(process.versions.node.split(".")[0], 10);
+  if (nodeMajor < 18) {
+    log(`${c.red}✗${c.reset} Need Node 18+. You have ${process.versions.node}.`);
+    process.exit(1);
+  }
+
+  if (!ghOk()) {
+    if (!runGhAuth()) {
+      log(`${c.red}✗${c.reset} GitHub authentication did not complete.`);
+      process.exit(1);
+    }
+  }
+  log(`${c.green}✓${c.reset} GitHub CLI session OK`);
+
+  const cfg = loadConfig(configPath);
+  const org = process.env.KOMPLIAN_ORG || cfg.org || "Komplian";
+
+  verifyOrgMembership(org);
+  logGhIdentity();
+  log(
+    `${c.green}✓${c.reset} Org ${c.bold}${org}${c.reset}: ${c.dim}active membership verified (GitHub API)${c.reset}`
+  );
+
+  banner();
+
+  let team = args.team;
+  if (!team && !args.yes && !args.allRepos) {
+    team = await pickTeam(cfg);
+  }
+
+  const repos = resolveRepos(cfg, org, team, args.allRepos);
+  if (repos.length === 0) {
+    log(`${c.red}✗${c.reset} No repositories to clone (permissions / team / org).`);
+    process.exit(1);
+  }
+
+  let workspace = args.workspace.trim();
+  if (!workspace) {
+    workspace = join(homedir(), "komplian");
+  }
+  const abs = resolve(workspace.replace(/^~(?=$|[/\\])/, homedir()));
+  if (!isSafeTargetDir(abs)) {
+    log(`${c.red}✗${c.reset} Refusing unsafe target directory: ${abs}`);
+    process.exit(1);
+  }
+
+  mkdirSync(abs, { recursive: true });
+  log("");
+  log(`${c.cyan}━━ Workspace ━━${c.reset} ${c.bold}${abs}${c.reset}`);
+  log(`${c.cyan}━━ Org ━━${c.reset} ${c.bold}${org}${c.reset}`);
+  if (team) log(`${c.cyan}━━ Team ━━${c.reset} ${c.bold}${team}${c.reset}`);
+  log(`${c.cyan}━━ Repos (${repos.length}) ━━${c.reset}`);
+  log("");
+
+  let failed = 0;
+  for (const name of repos) {
+    const ok = cloneOne(org, name, abs, args.ssh);
+    if (!ok) failed += 1;
+  }
+
+  copyCursorPack(abs, process.env.KOMPLIAN_CURSOR_REPO);
+
+  if (args.install) {
+    needCmd("npm");
+    npmInstallEach(abs);
+  }
+
+  log("");
+  log(`${c.cyan}━━ Done ━━${c.reset}`);
+  if (failed > 0) {
+    log(`${c.yellow}○${c.reset} ${failed} repo(s) failed — check access and retry.`);
+  }
+  log(`${c.green}✓${c.reset} Open in Cursor: ${c.bold}File → Open Folder → ${abs}${c.reset}`);
+  log(`${c.dim}  Copy .env.example → .env per project; secrets via 1Password — never commit.${c.reset}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/komplian-team-repos.json

@@ -0,0 +1,14 @@
+{
+  "_comment": "Map team slug (-t) → repo names in org. Align slugs with GitHub Team names or internal labels. Adjust when teams/repos change.",
+  "org": "Komplian",
+  "default_team": "platform",
+  "exclude_from_all": [],
+  "teams": {
+    "platform": ["app", "api", "web", "admin", "docs", "ai-tools"],
+    "backend": ["api", "ai-tools"],
+    "frontend": ["app", "web", "docs", "ai-tools"],
+    "admin": ["admin", "api", "ai-tools"],
+    "docs": ["docs", "web", "ai-tools"],
+    "growth": ["web", "docs", "ai-tools"]
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "komplian",
+  "version": "0.1.0",
+  "description": "Komplian developer workspace setup: GitHub CLI auth + clone repos by team (zero manual repo clone for developers — use npx).",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "komplian": "komplian-onboard.mjs"
+  },
+  "files": [
+    "komplian-onboard.mjs",
+    "komplian-team-repos.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "node --check komplian-onboard.mjs"
+  },
+  "keywords": [
+    "komplian",
+    "onboarding",
+    "github",
+    "cli"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Komplian/komplian.git"
+  }
+}