devworkspace 0.0.0-stage → 0.1.0

package/docs/testing.md

@@ -0,0 +1,58 @@
+# Testing contract and verification
+
+## The testing contract
+
+`devworkspace analyze` infers which verification commands the *project* has and stores them in `.devworkspace/context/commands.json`:
+
+| Check | Available | Command | Required |
+| --- | --- | --- | --- |
+| typecheck | yes | `npm run typecheck` | yes |
+| unit | yes | `npm test` | yes |
+| integration | yes | `npm run test:integration` | context |
+| e2e | yes | `npm run test:e2e` | context |
+| lint | yes | `npm run lint` | yes |
+| build | yes | `npm run build` | yes |
+
+`required` is `yes` (always applies to code changes), `context` (only when relevant to the change) or `no`. Entries you or the agent edit by hand get `origin: "user"` and are never overwritten by later analysis.
+
+Sources: `package.json` scripts (matched by common names), plus conventions for Python (pytest/ruff/mypy/black/alembic), Go, Rust, Maven and Gradle. npm's default `"no test specified"` placeholder is ignored.
+
+### Commands are untrusted input
+
+Everything marked `origin: "repository-script"` comes from files in the repository. DevWorkspace **never runs these commands itself**; the agent does, and the generated instructions tell it to read what a script does before running unfamiliar ones, especially where scripts might deploy, migrate or write over the network.
+
+## Task-specific verification
+
+Questions need none; docs need only documentation checks; bugs, features and refactors derive their checks from the contract (see [routing](routing.md)). Baseline handling:
+
+```bash
+devworkspace task tests <id> --phase baseline --passed 214 --failed 3   # before changing code
+devworkspace task tests <id> --phase after    --passed 218 --failed 3
+devworkspace task verify <id> unit pass
+```
+
+Pre-existing failures are recorded, not blamed on new work. Regressions block completion.
+
+## Failure reporting
+
+```text
+STATUS: BLOCKED
+Unit tests: FAIL   Typecheck: PASS   Lint: PASS   Build: FAIL
+Failure: <actual error>
+Task is not considered complete.
+```
+
+## Testing DevWorkspace itself
+
+```bash
+npm test                 # unit + integration + e2e (vitest)
+npm run test:unit | test:integration | test:e2e
+npm run coverage         # thresholds enforced (stricter on security, paths, tasks, knowledge, portability)
+npm run typecheck && npm run lint
+npm run smoke            # pack → install tarball into clean dirs → run the real CLI (local, --prefix, npx, PowerShell)
+npm run release:check    # the full pre-publish gate; never publishes
+```
+
+Layers: **unit** (pure logic, security, paths incl. `path.win32`, schemas, routing scenarios, prompts), **integration** (command flows through the real CLI in-process with a hermetic home directory), **e2e** (the ten acceptance scenarios, Windows-style paths, large repo simulation, concurrency, hostile imports). Fixtures live in `fixtures/` (Express, React/Vite, Next.js, NestJS, FastAPI, monorepo, no tests, failing tests, existing AI files, prompt injection); scenarios that need Git state, secrets or unusual paths are built at test time.
+
+The generated prompts are tested for *behaviour*, not snapshots: `prompts/requirements.ts` lists what every onboarding/refresh prompt must instruct (untrusted-data rule, no secrets, evidence, git safety, testing contract, completion gate, memory rules, …), and `validatePrompt` is used by the tests and by `doctor`.

package/docs/troubleshooting.md

@@ -0,0 +1,26 @@
+# Troubleshooting
+
+Start with `devworkspace doctor`. Every warning/failure includes a remediation line.
+
+| Problem | What to do |
+| --- | --- |
+| **Unsupported Node version** | Needs Node ≥ 20.11. `node -v`; install from nodejs.org or use nvm/fnm. `doctor` shows the requirement. |
+| **Git unavailable** | Install Git. DevWorkspace still works but cannot report branch/working-tree state or tracked-secret problems, and Claude cannot protect uncommitted changes. |
+| **Not a Git repository** | Fine. `status` shows `Git: not a repository`. Consider `git init` so changes can be reviewed and reverted. |
+| **"No DevWorkspace found"** | Run `devworkspace init` in the project root. Commands search upward from the current directory; use `--cwd <dir>` if you are elsewhere. |
+| **Graphify unavailable / no graph** | `uv tool install graphifyy` (or `pipx`), `graphify install --project`, then run `/graphify .` in Claude Code. DevWorkspace keeps working without it. |
+| **Agent Skills / Ponytail "Unverified"** | Claude Code owns plugin state, so this is best-effort. In Claude Code run `/plugin` to see installed plugins, or install: `/plugin marketplace add addyosmani/agent-skills` → `/plugin install agent-skills@addy-agent-skills`; `/plugin marketplace add DietrichGebert/ponytail` → `/plugin install ponytail@ponytail`. |
+| **Claude config conflict** (`agent install` reports `CONFLICT`) | Unbalanced `devworkspace:start/end` markers in `CLAUDE.md`, or a user-authored skill at `.claude/skills/devworkspace/`. Fix/remove the stray marker or rename your skill, then re-run. Nothing was changed. |
+| **Claude ignores my `AGENTS.md`** | Claude reads `AGENTS.md` only when no `CLAUDE.md` exists. `agent install` adds an `@AGENTS.md` import when it creates `CLAUDE.md`; if you created `CLAUDE.md` yourself, add `@AGENTS.md` to it. |
+| **Stale context** | `devworkspace refresh`, then paste `.devworkspace/analysis/refresh-prompt.md` into Claude. Facts without cited `--file` sources can never be proven stale. |
+| **Corrupted workspace** (`malformed JSON`, schema errors) | `git checkout -- .devworkspace/<file>`; or copy a backup from `.devworkspace/local/backups/`. A newer-schema file means upgrade DevWorkspace. Leftover `*.tmp` files come from an interrupted write and are safe to delete. |
+| **"Another DevWorkspace process is modifying this workspace"** | Wait. If no DevWorkspace process is running, delete `.devworkspace/local/workspace.lock` (stale locks from dead processes are normally broken automatically). |
+| **Tests were failing before my task** | Record a baseline: `devworkspace task tests <id> --phase baseline --passed N --failed M`. Only *increases* in failures block completion. |
+| **Project moved / different drive** | Nothing to do; identity is an id, not a path. `doctor` warns if knowledge contains absolute paths. |
+| **Package manager unavailable** | The testing contract is inferred from files, so it lists `pnpm`/`yarn` commands even if not installed. Edit `context/commands.json` (set `origin: "user"`) to use what you have. |
+| **Windows: `EPERM` on write** | Editors, antivirus or indexers can briefly lock files; writes retry for ~2 s. If it persists, close the program holding the file. |
+| **Windows: PowerShell blocks `devworkspace.ps1`** | `npm` creates `.cmd` and `.ps1` shims. Run via `devworkspace.cmd`, `npx devworkspace`, or relax the execution policy for your user (`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`). |
+| **`.devworkspace` not appearing in Git** | The root `.gitignore` ignores it. Remove that rule; `.devworkspace/.gitignore` already excludes the machine-local parts. |
+| **Analysis seems incomplete** | `status`/`doctor` says "partial" when file or depth limits were hit. Raise `settings.maxFiles` in `project.json` or add `.devworkspaceignore` entries for generated folders. |
+
+Add `--debug` to any command for stack traces and debug logs (secrets are still redacted).

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "devworkspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "devworkspace": "dist/cli/main.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "!docs/implementation"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "coverage": "vitest run --coverage",
+    "audit:security": "npm audit --omit=dev --audit-level=high",
+    "smoke": "node scripts/smoke.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "claude-code",
+    "agent",
+    "workspace",
+    "developer-tools",
+    "knowledge",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SHIKHIL8137/devworkspace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SHIKHIL8137/devworkspace/issues"
+  },
+  "homepage": "https://github.com/SHIKHIL8137/devworkspace#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.4",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  }
+}