@ui8kit/uxdx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ui8kit
+
+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,38 @@
+# UXDX
+
+CLI to accumulate operator and developer experience packs. One binary, two
+commands. Package name: [`@ui8kit/uxdx`](https://www.npmjs.com/package/@ui8kit/uxdx).
+
+Homepage: [github.com/ui8kit/uxdx](https://github.com/ui8kit/uxdx)
+
+```text
+npx @ui8kit/uxdx --help
+npx @ui8kit/uxdx project | p | -p | --project  [init] [--dir <path>] [--rules] [--force]
+npx @ui8kit/uxdx sdlc    | s | -s | --sdlc     [init] [--dir <path>] --level light|core|full [--force] [--no-install]
+```
+
+Same via Bun: `bunx @ui8kit/uxdx --help`.
+
+The binary is still `uxdx`. After a local or global install you can call it
+without the scope:
+
+```bash
+npm i -g @ui8kit/uxdx
+uxdx --help
+
+npm i -D @ui8kit/uxdx
+npx uxdx --help
+```
+
+- `project` writes `README.md`, `.gitignore`, `.cursorignore`, and `.manual/`.
+- `sdlc` copies a vendored harness pack into `.sdlc/`. `--level` is required.
+- After copy, `sdlc` runs `.sdlc/sdlc.sh install` unless `--no-install`.
+
+## Local
+
+```bash
+bun install
+bun test
+bun run uxdx -- --help
+bun run build
+```

package/dist/uxdx.mjs

@@ -0,0 +1,296 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// packages/cli/src/parse.ts
+var LEVELS = new Set(["light", "core", "full"]);
+function takeFlag(rest, name) {
+  const i = rest.indexOf(name);
+  if (i === -1)
+    return false;
+  rest.splice(i, 1);
+  return true;
+}
+function takeOpt(rest, name) {
+  const i = rest.indexOf(name);
+  if (i === -1)
+    return null;
+  const v = rest[i + 1];
+  if (!v || v.startsWith("-")) {
+    throw new Error(`${name} requires a value`);
+  }
+  rest.splice(i, 2);
+  return v;
+}
+function stripInit(rest) {
+  if (rest[0] === "init")
+    rest.shift();
+}
+function parseArgv(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0)
+    return { command: "help" };
+  const head = args[0];
+  const rest = args.slice(1);
+  if (head === "--help" || head === "-h") {
+    if (rest[0] === "-p" || rest[0] === "--project" || rest[0] === "p" || rest[0] === "project") {
+      return parseProject(rest.slice(1), true);
+    }
+    if (rest[0] === "-s" || rest[0] === "--sdlc" || rest[0] === "s" || rest[0] === "sdlc") {
+      return parseSdlc(rest.slice(1), true);
+    }
+    return { command: "help" };
+  }
+  if (head === "-p" || head === "--project" || head === "p" || head === "project") {
+    return parseProject(rest, false);
+  }
+  if (head === "-s" || head === "--sdlc" || head === "s" || head === "sdlc") {
+    return parseSdlc(rest, false);
+  }
+  throw new Error(`unknown command ${head} (try --help)`);
+}
+function parseProject(restIn, forcedHelp) {
+  const rest = [...restIn];
+  stripInit(rest);
+  const help = forcedHelp || takeFlag(rest, "--help") || takeFlag(rest, "-h");
+  const force = takeFlag(rest, "--force");
+  const rules = takeFlag(rest, "--rules");
+  const dir = takeOpt(rest, "--dir") ?? process.cwd();
+  if (rest.length)
+    throw new Error(`unexpected arguments: ${rest.join(" ")}`);
+  return { command: "project", help, dir, force, rules };
+}
+function parseSdlc(restIn, forcedHelp) {
+  const rest = [...restIn];
+  stripInit(rest);
+  const help = forcedHelp || takeFlag(rest, "--help") || takeFlag(rest, "-h");
+  const force = takeFlag(rest, "--force");
+  const noInstall = takeFlag(rest, "--no-install");
+  const dir = takeOpt(rest, "--dir") ?? process.cwd();
+  const levelRaw = takeOpt(rest, "--level");
+  let level = null;
+  if (levelRaw) {
+    if (!LEVELS.has(levelRaw))
+      throw new Error(`--level must be light, core, or full`);
+    level = levelRaw;
+  }
+  if (rest.length)
+    throw new Error(`unexpected arguments: ${rest.join(" ")}`);
+  return {
+    command: "sdlc",
+    help,
+    dir,
+    force,
+    level,
+    install: !noInstall
+  };
+}
+var ROOT_HELP = `uxdx — operator and developer experience packs
+
+Usage:
+  uxdx [--help]
+  uxdx project | p | -p | --project  [init] [--dir <path>] [--rules] [--force]
+  uxdx sdlc    | s | -s | --sdlc     [init] [--dir <path>] --level light|core|full [--force] [--no-install]
+
+  -p / --project   Scaffold README, ignores, and .manual/
+  -s / --sdlc      Install an SDLC harness pack into .sdlc/
+
+Run uxdx project --help or uxdx sdlc --help for command flags.
+`;
+var PROJECT_HELP = `uxdx project — default operator layout
+
+Aliases: project, p, -p, --project
+
+  [init]         Default action (may be omitted)
+  --dir <path>   Target directory (default: cwd)
+  --rules        Create a stub .cursor/rules file
+  --force        Overwrite files this command owns
+  --help         This text
+`;
+var SDLC_HELP = `uxdx sdlc — install an SDLC harness into .sdlc/
+
+Aliases: sdlc, s, -s, --sdlc
+
+  [init]              Default action (may be omitted)
+  --level <name>      Required: light | core | full
+  --dir <path>        Target directory (default: cwd)
+  --no-install        Copy the pack only; do not run .sdlc/sdlc.sh install
+  --force             Replace an existing .sdlc of a different level
+  --help              This text
+`;
+
+// packages/project/src/init.ts
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+function ensureLine(file, line, _force) {
+  if (!existsSync(file)) {
+    writeFileSync(file, `${line}
+`);
+    return;
+  }
+  const cur = readFileSync(file, "utf8");
+  if (cur.split(/\r?\n/).some((l) => l.trim() === line.trim()))
+    return;
+  const nl = cur.endsWith(`
+`) || cur.length === 0 ? "" : `
+`;
+  writeFileSync(file, `${cur}${nl}${line}
+`);
+}
+function writeIfMissing(file, body, force) {
+  if (existsSync(file) && !force)
+    return;
+  writeFileSync(file, body);
+}
+function initProject(opts) {
+  const root = opts.dir;
+  mkdirSync(root, { recursive: true });
+  const done = [];
+  const name = basename(root);
+  const readme = join(root, "README.md");
+  writeIfMissing(readme, `# ${name}
+`, opts.force);
+  done.push("README.md");
+  ensureLine(join(root, ".gitignore"), ".manual/", opts.force);
+  done.push(".gitignore");
+  ensureLine(join(root, ".cursorignore"), ".manual/", opts.force);
+  done.push(".cursorignore");
+  const projectDir = join(root, ".project");
+  mkdirSync(projectDir, { recursive: true });
+  writeIfMissing(join(projectDir, "README.md"), `# .project
+
+Operator notes for this repository. See \`intent.md\` when present.
+`, opts.force);
+  done.push(".project/");
+  mkdirSync(join(root, ".manual"), { recursive: true });
+  done.push(".manual/");
+  if (opts.rules) {
+    const rulesDir = join(root, ".cursor", "rules");
+    mkdirSync(rulesDir, { recursive: true });
+    writeIfMissing(join(rulesDir, "uxdx.mdc"), `---
+description: UXDX operator layout
+alwaysApply: true
+---
+
+# UXDX
+
+Read the repository operator notes before changing product scope.
+`, opts.force);
+    done.push(".cursor/rules/");
+  }
+  return done;
+}
+
+// packages/sdlc/src/init.ts
+import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+function harnessRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "..", "harness"),
+    join2(here, "..", "..", "harness"),
+    join2(here, "..", "packages", "sdlc", "harness"),
+    join2(process.cwd(), "packages", "sdlc", "harness")
+  ];
+  for (const c of candidates) {
+    if (existsSync2(join2(c, "light", "manifest.yaml")))
+      return c;
+  }
+  throw new Error("uxdx: SDLC harness packs not found (packages/sdlc/harness)");
+}
+function readLevel(manifestPath) {
+  if (!existsSync2(manifestPath))
+    return null;
+  const m = readFileSync2(manifestPath, "utf8").match(/^level:\s*(\S+)/m);
+  return m ? m[1] : null;
+}
+function initSdlc(opts) {
+  const dest = join2(opts.dir, ".sdlc");
+  const existing = readLevel(join2(dest, "manifest.yaml"));
+  if (existing && existing !== opts.level && !opts.force) {
+    throw new Error(`uxdx: .sdlc already has level ${existing}; use --force to replace with ${opts.level}`);
+  }
+  const src = join2(harnessRoot(), opts.level);
+  if (!existsSync2(join2(src, "manifest.yaml"))) {
+    throw new Error(`uxdx: missing harness pack ${opts.level}`);
+  }
+  mkdirSync2(opts.dir, { recursive: true });
+  if (existsSync2(dest) && opts.force) {
+    rmSync(dest, { recursive: true, force: true });
+  }
+  mkdirSync2(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  let installed = false;
+  if (opts.install) {
+    const script = join2(dest, "sdlc.sh");
+    const r = spawnSync("bash", [script, "install"], {
+      cwd: opts.dir,
+      encoding: "utf8"
+    });
+    if (r.error || r.status !== 0) {
+      const err = r.stderr || r.error?.message || `exit ${r.status}`;
+      throw new Error(`uxdx: .sdlc/sdlc.sh install failed (${err.trim()})`);
+    }
+    installed = true;
+  }
+  return { sdlcDir: dest, installed };
+}
+
+// packages/cli/src/main.ts
+function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgv(argv);
+  } catch (e) {
+    console.error(`uxdx: ${e.message}`);
+    return 1;
+  }
+  if (parsed.command === "help") {
+    console.log(ROOT_HELP);
+    return 0;
+  }
+  if (parsed.command === "project") {
+    if (parsed.help) {
+      console.log(PROJECT_HELP);
+      return 0;
+    }
+    const done = initProject({
+      dir: parsed.dir,
+      force: parsed.force,
+      rules: parsed.rules
+    });
+    console.log(`uxdx: project init in ${parsed.dir}`);
+    for (const p of done)
+      console.log(`  ${p}`);
+    return 0;
+  }
+  if (parsed.help) {
+    console.log(SDLC_HELP);
+    return 0;
+  }
+  if (!parsed.level) {
+    console.error("uxdx: --level is required (light | core | full)");
+    console.log(SDLC_HELP);
+    return 1;
+  }
+  try {
+    const { sdlcDir, installed } = initSdlc({
+      dir: parsed.dir,
+      level: parsed.level,
+      force: parsed.force,
+      install: parsed.install
+    });
+    console.log(`uxdx: sdlc ${parsed.level} → ${sdlcDir}${installed ? " (install ran)" : ""}`);
+    return 0;
+  } catch (e) {
+    console.error(e.message);
+    return 1;
+  }
+}
+if (__require.main == __require.module) {
+  process.exit(run(process.argv));
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ui8kit/uxdx",
+  "version": "0.1.0",
+  "description": "CLI to accumulate operator and developer experience packs",
+  "type": "module",
+  "bin": {
+    "uxdx": "./dist/uxdx.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ui8kit/uxdx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ui8kit/uxdx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "packages/sdlc/harness",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cli",
+    "uxdx",
+    "sdlc",
+    "cursor",
+    "scaffold",
+    "ui8kit"
+  ],
+  "author": {
+    "name": "ui8kit",
+    "url": "https://github.com/ui8kit"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ui8kit/uxdx",
+  "scripts": {
+    "build": "bun build packages/cli/src/main.ts --outfile dist/uxdx.mjs --target node",
+    "uxdx": "bun packages/cli/src/main.ts",
+    "test": "bun test",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun test && bun run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "workspaces": [
+    "packages/*"
+  ]
+}

package/packages/sdlc/harness/README.md

@@ -0,0 +1,58 @@
+# SDLC harness packs (solo)
+
+Copy-paste packs for the AI-native loop, sized for one operator. Source method:
+[`.manual/sdlc-en`](../.manual/sdlc-en/README.md). Which product gets which pack:
+[`.project/sdlc-scope.md`](../.project/sdlc-scope.md).
+
+Later this tree can move to its own repo or a CLI (`sdlc init --level full`).
+Until then the consumer copies **one** pack into **`.sdlc/`**.
+
+## How it works
+
+```
+hinddy/brainstorm/.harness-sdlc/<level>/     (this gym)
+        │
+        │  copy (do not merge levels)
+        ▼
+your-repo/.sdlc/                             artifacts + overlay text
+        │
+        ├── intent.md  spec.md  plan.md      templates at pack root
+        ├── changes/<slug>/                  one folder per real change
+        ├── AGENTS.md                        overlay — merge into root AGENTS.md
+        ├── skills/                          copy → .cursor/skills/
+        └── cursor/rules/                    copy → .cursor/rules/
+```
+
+1. Pick **full**, **core**, or **light** from `sdlc-scope.md`. Never stack two packs.
+2. Copy the pack directory contents into `<repo>/.sdlc/` (keep `manifest.yaml`).
+3. **Activate Cursor** (rules/skills are not loaded from `.sdlc` by default):
+
+   ```bash
+   mkdir -p .cursor/rules .cursor/skills
+   cp .sdlc/cursor/rules/*.mdc .cursor/rules/
+   cp -R .sdlc/skills/* .cursor/skills/
+   ```
+
+4. **AGENTS.md**: if the repo already has a product `AGENTS.md` (SiteStarter, YPanel, …), **append** a short pointer. Do not replace stack-contract text. If there is no root file, copy `.sdlc/AGENTS.md` to the repo root.
+5. For each change: copy `intent.md` / `spec.md` / `plan.md` into `.sdlc/changes/<slug>/` and fill them. Leave the pack-root files as templates.
+6. Existing product rules (`.cursor/rules/stack-contract.mdc`, …) stay. The harness adds SDLC rules; it does not own Codex IA.
+
+Human still merges. The agent writes artifacts and code; you accept `plan.md` before a large diff.
+
+## Levels
+
+| Pack | Use when | Artifacts | Extra |
+| --- | --- | --- | --- |
+| `light/` | Product on an existing contract; small blast radius | `plan.md` required; `intent.md` optional; skip `spec.md` unless IA changes | No evals, no maintain bands |
+| `core/` | Kernel, API, ARIA, shared library | `intent.md` + `plan.md`; compressed `spec.md` on boundary changes | Invariant skills; short `REVIEW.md` |
+| `full/` | Portable Codex path, YPanel, anything that ships + is pinned | Full chain including `spec.md` | `REVIEW.md`, `evals/` stub, `bands.yaml` stub |
+
+## Future CLI (not built)
+
+Suggested commands, matching `manifest.yaml` in each pack:
+
+- `sdlc init --level full` → copy pack to `.sdlc`, overlay rules/skills, patch root `AGENTS.md` between markers
+- `sdlc change start <slug>` → copy templates into `.sdlc/changes/<slug>/`
+- `sdlc change accept` → remind to commit artifacts with the diff
+
+Do not invent a second content REST or product kinds from this harness.

package/packages/sdlc/harness/core/AGENTS.md

@@ -0,0 +1,12 @@
+<!-- sdlc-harness:begin -->
+## SDLC harness (core)
+
+This repo uses the **core** pack (`.harness-sdlc/core` → `.sdlc/`).
+
+- Boundary, API, and policy changes: `intent.md` + short `spec.md` + `plan.md`.
+- Mechanical fixes: `plan.md` only, still name the invariant you must not break.
+- Skills: `sdlc-invariants`, `sdlc-plan`. Rule: `sdlc-core.mdc`.
+- PR review against `.sdlc/REVIEW.md` (bugs, contract, compatibility).
+- Do not add product behaviour to this module to ship a site. Consumers pin.
+- Human merge. Skip eval-CI and maintain-bands unless this repo already runs them.
+<!-- sdlc-harness:end -->

package/packages/sdlc/harness/core/README.md

@@ -0,0 +1,15 @@
+# Core harness
+
+For kernels, shared libraries, and high blast-radius contracts.
+Examples: FormSet, Framework, Panel, ui8kit/aria, Context.
+
+Copy this directory to `<repo>/.sdlc/`. Overlay Cursor files — `../README.md`.
+
+## Per change
+
+1. Write `intent.md` when the change is a boundary, policy, or public API.
+2. Keep `spec.md` short: constraints + concerns, not a product PRD.
+3. `plan.md` always names files, order, tests, and what must not break.
+4. Encode repeated invariants as skills; do not repeat them in every plan.
+5. Human merge. No on-call agent. No eval suite unless this repo already has CI
+   for agent config (then add cases there, not a second framework).

package/packages/sdlc/harness/core/REVIEW.md

@@ -0,0 +1,18 @@
+# Review instructions (core)
+
+## Passes
+
+Tag each finding with its pass:
+
+- Bugs: logic errors, broken edge cases, subtle regressions
+- Contract: public API, ARIA, kernel boundary, generated-file policy
+- Compatibility: importers / pins still valid
+
+## Important vs nit
+
+Important: would break callers, leak data, or violate the module contract.
+Style and naming are nits. Cap nits at five; count the rest.
+
+## Do not report
+
+Generated files the repo forbids editing, and anything CI already enforces.

package/packages/sdlc/harness/core/changes/README.md

@@ -0,0 +1,4 @@
+# changes/
+
+Copy `../intent.md`, `../spec.md`, and `../plan.md` into `./<slug>/` for a
+boundary change. Mechanical work may keep `plan.md` only.

package/packages/sdlc/harness/core/cursor/rules/sdlc-core.mdc

@@ -0,0 +1,15 @@
+---
+description: Core SDLC — invariants, compressed spec, plan before large diffs
+alwaysApply: true
+---
+
+# Core SDLC overlay
+
+This repository opted into `.sdlc` harness **core**.
+
+- Artifacts: `.sdlc/changes/<slug>/`.
+- Boundary changes need `intent.md`, a short `spec.md`, and `plan.md`.
+- Review incoming diffs against `.sdlc/REVIEW.md`.
+- Skills `sdlc-invariants` and `sdlc-plan` apply.
+- Product `AGENTS.md` and stack-contract win on conflict.
+- No autonomous production actions. No second content API.

package/packages/sdlc/harness/core/install.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/sdlc.sh" install "$@"

package/packages/sdlc/harness/core/intent.md

@@ -0,0 +1,25 @@
+# Intent (core)
+
+Author: <!-- name -->
+Status: draft
+Slug: <!-- kebab-case -->
+
+## Problem
+
+What invariant, API, or shared behaviour is wrong or missing.
+
+## Proposed outcome
+
+The new contract in one paragraph. Name the callers that must keep working.
+
+## Affected users and systems
+
+Who imports this module. Do not expand into product IA of a consumer site.
+
+## Constraints
+
+- Callers pin this module; do not require them to fork.
+- No product schemas, carts, or site-specific kinds in a shared kernel.
+- Existing tests that encode the compiler/API contract stay green.
+
+## Open questions

package/packages/sdlc/harness/core/manifest.yaml

@@ -0,0 +1,15 @@
+level: core
+version: 1
+copy_to: .sdlc
+cursor:
+  rules: cursor/rules
+  skills: skills
+agents_md:
+  overlay: AGENTS.md
+  merge_markers:
+    begin: "<!-- sdlc-harness:begin -->"
+    end: "<!-- sdlc-harness:end -->"
+artifacts:
+  required: [plan.md]
+  on_boundary_change: [intent.md, spec.md]
+review: REVIEW.md

package/packages/sdlc/harness/core/plan.md

@@ -0,0 +1,25 @@
+# Plan (core)
+
+From: `.sdlc/changes/<slug>/spec.md` (or intent if spec was skipped)
+Status: draft
+
+## Files that change
+
+-
+
+## Order of work
+
+1.
+2.
+
+## Proof
+
+Commands that must pass (repo SoT: `AGENTS.md` / Makefile / `bun run`).
+
+## Risks
+
+Blast radius for importers. Generated paths, frozen packages, public API.
+
+## Rollback
+
+How to revert the pin in callers if this ships broken.