superdev-cli 0.1.0

package/SECURITY.md

@@ -0,0 +1,135 @@
+# Security
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting on this repository:
+**Security > Report a vulnerability**, at
+https://github.com/superdev-ai/superdev/security/advisories/new
+
+That channel is private between you and the maintainer, which is what makes a
+report safe before a fix exists. **Please do not open a public issue for a
+security problem**, and do not describe one in a pull request, a discussion or a
+fork, because there is no coordinated disclosure process running alongside it to
+contain a public report.
+
+If private reporting is unavailable to you for any reason, open a public issue
+saying only that you have a security report and asking for a private channel.
+Say nothing about the problem itself in it.
+
+**What to expect, stated honestly.** This is maintained by one person and nobody
+is on rota, so no response time is promised. What is promised is that a report is
+read, that you are told what was concluded, and that you are credited in the fix
+unless you ask not to be.
+
+**Supported versions.** The latest released version only. There is no long-term
+support branch and no backporting: a fix ships as a new release of
+`superdev-cli` and a new plugin tag, which share one version number.
+
+| Version | Supported |
+|---|---|
+| Latest release | Yes |
+| Anything older | No, update first |
+
+## What Superdev is not
+
+Superdev is a development orchestrator, not a security sandbox, and does not try
+to be one. It runs inside an agent harness that already has file system access
+and the ability to run commands. Destructive, outward-facing and irreversible
+actions are governed by that harness's permission model, plus explicit
+confirmation in the skills. If your harness is configured to approve everything,
+Superdev does not add a second line of defence.
+
+Treat the project database and the generated documentation as trusted only as
+far as you trust whoever wrote to them.
+
+## The local service
+
+The control center is served by one local process, started by the CLI and never
+run separately.
+
+- It binds to `127.0.0.1` on port 4317 by default.
+- A request that reaches the service under a name that is not loopback is
+  refused with `E_FOREIGN_HOST`. That check runs ahead of every route, reads and
+  the event stream included, and it is what defeats DNS rebinding, where an
+  attacker-controlled name resolves to `127.0.0.1`.
+- Any `/api/` request that is not same-origin is refused with `E_CROSS_ORIGIN`.
+  That covers reads, not only writes, which is what stops a page on another
+  origin reading your project through the browser. Verified: a request to
+  `/api/overview` carrying a foreign `Origin` header returns 403.
+- `/health` returns an instance token so the process manager can confirm it is
+  talking to its own service rather than to something else that took the port.
+  The token is masked in text output and appears only in `--json`.
+
+## The write surface
+
+The browser cannot send SQL, a shell command or a file path. Every write goes
+through one endpoint, `POST /api/mutations`, taking `{ action, payload }`
+against an allowlist of 22 named actions. There is no generic query endpoint and
+no path parameter that reaches the file system.
+
+The HTTP surface is fixed and small: ten read routes in a table, two resolved in
+the server, `/health`, `/api/events`, `/api/mutations`, and `GET` or `HEAD` on
+`/` for the interface itself.
+
+## History that cannot be quietly rewritten
+
+Some tables are append-only, enforced by database triggers rather than by
+convention: `activity_events`, `decision_transitions` and `status_history` each
+raise `E_APPEND_ONLY` on update and on delete. Decision transitions are
+hash-chained, each row storing a sha256 over the previous hash, the sequence,
+the from and to status and the timestamp, so a rewritten transition breaks the
+chain visibly.
+
+This makes tampering detectable. It does not make it impossible: the database is
+an ordinary SQLite file and anyone with write access to the disk can replace it.
+
+## Installing providers
+
+Superdev never installs anything implicitly. `scripts/doctor/doctor.mjs plan`
+computes a sha256 `planId` over the exact commands it intends to run, and
+`apply` refuses unless both `--plan-id` and `--consent` are supplied and the
+recomputed id still matches. Commands are executed as argument arrays, never
+through a shell. A command containing shell metacharacters is rejected, as is
+one carrying a blanket flag such as `--all`, `-y` or `--yes`.
+
+## Data leaving the machine
+
+Superdev's own code makes no outbound network request. The only network module
+imported anywhere under `src/` or `scripts/` is `node:http`, used for the
+loopback server and the client that talks to it. There is no telemetry, no
+analytics and no crash reporting. The committed control center bundle fetches
+only `/api/` paths.
+
+Two things do reach the network, and neither is Superdev sending your data:
+`npm install` fetches the runtime dependency from the public npm registry once,
+and a consented provider install runs that provider's own installer.
+
+The agent harness Superdev runs inside is a separate program with its own
+network behaviour. Superdev neither controls nor observes it.
+
+## Content screening
+
+Content is screened at the storage boundary, in `src/model/screening.mjs`, so
+certain shapes never reach the database: secret-shaped strings, absolute home
+paths, em dashes, emoji and model reasoning fields. Screening refuses with the
+exact field rather than advising. This is a hygiene measure against accidental
+capture, not a secret scanner you should rely on. Handling real secrets is
+routed to the envx provider.
+
+## Known limits
+
+Stated because they are true, not because they are comfortable.
+
+- The privacy scan over git history, `npm run scan:history`, passes on this
+  history. It did not pass on the history this repository was developed in: a
+  brand asset carried a third party's email address in its metadata, and a
+  history cannot be cleaned without rewriting it. This repository was therefore
+  published from a fresh initial commit rather than by rewriting a history whose
+  earlier state had already been distributed. The development history is not
+  public.
+- On Codex, lifecycle hooks do not fire until each hook is explicitly trusted,
+  and Codex tool hooks cover shell commands only, so edit-triggered staleness
+  marking never fires there.
+- `references/confidentiality.md` states that the denylist and staged scans run
+  before every commit. Nothing enforces that: there is no committed hook
+  installer. They are commands a maintainer runs.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,253 @@
+# Third-party notices
+
+Superdev itself is Copyright 2026 Rahul Retnan, licensed under the Apache
+License 2.0. See `LICENSE` for the terms and `NOTICE` for the attribution
+notice that accompanies them.
+
+This file exists because Superdev redistributes other people's code. The
+control center is compiled from `ui/` into a single committed file,
+`src/service/assets/control-center.html`, and that file is a compiled copy of
+React, Radix UI, xyflow, lucide, cmdk, dagre, zustand, d3 and the rest of the
+interface dependency tree. The bundler strips upstream comments, so a search
+for the word "copyright" inside that file returns nothing. MIT, ISC and
+BSD-3-Clause all require the copyright notice and the permission notice to
+travel with copies, including compiled copies. This file is where they travel.
+
+The notices below cover:
+
+- `src/service/assets/control-center.html`, which is tracked by git.
+- Any package assembled from this tree, including the standalone package built
+  by `scripts/package/build-standalone.mjs`, which copies the same file.
+
+They do not cover `node_modules`. That directory is git-ignored, is installed
+by the consumer's own package manager from the public registry, and carries
+each package's own licence file as published.
+
+## How this list was produced
+
+The list is the production dependency tree of `ui/`, taken from
+`npm ls --omit=dev --all` in that directory, with each package's `license`
+field and the copyright lines from its own licence file. Type-only packages
+(`@types/*`, `csstype`) are excluded because they contribute no code to the
+bundle. `tailwindcss` is a dev dependency of `ui/`, but its generated CSS is
+part of the bundle, so it is listed.
+
+Re-derive the list with the same command after any change to `ui/package.json`.
+
+## MIT
+
+The following packages are distributed under the MIT licence. The copyright
+holder for each is listed; the permission notice follows once, because the text
+is identical for all of them.
+
+| Package | Version | Copyright |
+| --- | --- | --- |
+| @floating-ui/core | 1.8.0 | Copyright (c) 2021-present Floating UI contributors |
+| @floating-ui/dom | 1.8.0 | Copyright (c) 2021-present Floating UI contributors |
+| @floating-ui/react-dom | 2.1.9 | Copyright (c) 2021-present Floating UI contributors |
+| @floating-ui/utils | 0.2.12 | Copyright (c) 2021-present Floating UI contributors |
+| @radix-ui/number | 1.1.3 | Copyright (c) 2022 WorkOS |
+| @radix-ui/primitive | 1.1.7 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-arrow | 1.1.15 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-collection | 1.1.15 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-compose-refs | 1.1.5 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-context | 1.2.2 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-dialog | 1.1.23 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-direction | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-dismissable-layer | 1.1.19 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-dropdown-menu | 2.1.24 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-focus-guards | 1.1.6 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-focus-scope | 1.1.16 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-id | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-menu | 2.1.24 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-popover | 1.1.23 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-popper | 1.3.7 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-portal | 1.1.17 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-presence | 1.1.10 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-primitive | 2.1.10 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-progress | 1.1.16 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-roving-focus | 1.1.19 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-scroll-area | 1.2.18 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-select | 2.3.7 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-separator | 1.1.15 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-slot | 1.3.3 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-switch | 1.3.7 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-tabs | 1.1.21 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-tooltip | 1.2.16 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-callback-ref | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-controllable-state | 1.2.6 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-effect-event | 0.0.5 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-is-hydrated | 0.1.3 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-layout-effect | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-previous | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-rect | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-use-size | 1.1.4 | Copyright (c) 2022 WorkOS |
+| @radix-ui/react-visually-hidden | 1.2.11 | Copyright (c) 2022 WorkOS |
+| @radix-ui/rect | 1.1.3 | Copyright (c) 2022 WorkOS |
+| @xyflow/react | 12.11.2 | Copyright (c) 2019-2025 webkid GmbH |
+| @xyflow/system | 0.0.79 | Copyright (c) 2019-2025 webkid GmbH |
+| aria-hidden | 1.2.6 | Copyright (c) 2017 Anton Korzunov |
+| classcat | 5.0.5 | Copyright (c) Jorge Bucaran |
+| clsx | 2.1.1 | Copyright (c) Luke Edwards (lukeed.com) |
+| cmdk | 1.1.1 | Copyright (c) 2022 Paco Coursey |
+| dagre | 0.8.5 | Copyright (c) 2012-2014 Chris Pettitt |
+| detect-node-es | 1.1.0 | Copyright (c) 2017 Ilya Kantor |
+| get-nonce | 1.0.1 | Copyright (c) 2020 Anton Korzunov |
+| graphlib | 2.1.8 | Copyright (c) 2012-2014 Chris Pettitt |
+| lodash | 4.18.1 | Copyright OpenJS Foundation and other contributors, based on Underscore.js, copyright Jeremy Ashkenas, DocumentCloud and Investigative Reporters and Editors |
+| react | 19.2.8 | Copyright (c) Meta Platforms, Inc. and affiliates |
+| react-dom | 19.2.8 | Copyright (c) Meta Platforms, Inc. and affiliates |
+| react-remove-scroll | 2.7.2 | Copyright (c) 2017 Anton Korzunov |
+| react-remove-scroll-bar | 2.3.8 | Anton Korzunov (see "Unresolved" below) |
+| react-style-singleton | 2.2.3 | Copyright (c) 2017 Anton Korzunov |
+| scheduler | 0.27.0 | Copyright (c) Meta Platforms, Inc. and affiliates |
+| tailwind-merge | 3.6.0 | Copyright (c) 2021 Dany Castillo |
+| tailwindcss | 4.3.3 | Copyright (c) Tailwind Labs, Inc. |
+| use-callback-ref | 1.3.3 | Copyright (c) 2017 Anton Korzunov |
+| use-sidecar | 1.1.3 | Copyright (c) 2017 Anton Korzunov |
+| use-sync-external-store | 1.6.0 | Copyright (c) Meta Platforms, Inc. and affiliates |
+| zustand | 4.5.7 | Copyright (c) 2019 Paul Henschel |
+
+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.
+
+## ISC
+
+| Package | Version | Copyright |
+| --- | --- | --- |
+| d3-color | 3.1.0 | Copyright 2010-2022 Mike Bostock |
+| d3-dispatch | 3.0.1 | Copyright 2010-2021 Mike Bostock |
+| d3-drag | 3.0.0 | Copyright 2010-2021 Mike Bostock |
+| d3-interpolate | 3.0.1 | Copyright 2010-2021 Mike Bostock |
+| d3-selection | 3.0.0 | Copyright 2010-2021 Mike Bostock |
+| d3-timer | 3.0.1 | Copyright 2010-2021 Mike Bostock |
+| d3-transition | 3.0.1 | Copyright 2010-2021 Mike Bostock |
+| d3-zoom | 3.0.0 | Copyright 2010-2021 Mike Bostock |
+| lucide-react | 0.545.0 | Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2023 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2025. |
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+Portions of lucide-react derive from Feather, under the MIT licence:
+
+Copyright (c) 2013-2023 Cole Bemis
+
+The MIT permission notice is reproduced in the MIT section above and applies to
+those portions.
+
+## BSD-3-Clause
+
+`d3-ease` 3.0.1.
+
+Copyright 2010-2021 Mike Bostock
+Copyright 2001 Robert Penner
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author nor the names of contributors may be used to
+  endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## 0BSD
+
+`tslib` 2.8.1.
+
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+## Apache-2.0
+
+`class-variance-authority` 0.7.1, Copyright 2022 Joe Bell.
+
+The full licence text is the same Apache License 2.0 reproduced in this
+repository's `LICENSE` file. That package ships no NOTICE file, so section 4(d)
+of the licence imposes no further obligation here.
+
+## Vendored source
+
+The 20 files in `ui/src/components/ui/` are derived from shadcn/ui. shadcn/ui
+is distributed as source to be copied into a project rather than installed as a
+package, so there is no dependency entry for it and no licence file in
+`node_modules`. Its published terms are the MIT licence. The copied files carry
+no attribution header today; see "Unresolved" below.
+
+## The runtime dependency
+
+Superdev's own runtime has one dependency, `@tursodatabase/database` 0.7.1,
+which declares the MIT licence in its `package.json`. It is installed by the
+consumer, not vendored into this repository and not embedded in any committed
+artifact, so no notice from it is redistributed here.
+
+## Unresolved
+
+These are known gaps, recorded rather than papered over.
+
+- `react-remove-scroll-bar` 2.3.8 declares the MIT licence in its
+  `package.json` but ships no licence file, so no copyright line could be read
+  from the package itself. It is authored by Anton Korzunov, the author of the
+  sibling `react-remove-scroll` packages listed above.
+- `ui/src/assets/logo.png` has no recorded provenance. No document in this
+  repository states who made it or under what terms, and it is redistributed
+  inside the committed bundle. This must be settled before the repository is
+  published.
+- No copyright holder is named for Superdev itself. The `LICENSE` file is the
+  unmodified Apache text with the appendix placeholder intact. The Apache grant
+  runs from the Licensor, so a downstream user cannot currently tell whose
+  grant they hold.
+- This file is maintained by hand. Nothing in `npm run validate` checks it
+  against `ui/package.json`, so it can fall behind a dependency change without
+  failing a gate.

package/hooks/hooks.json

@@ -0,0 +1,61 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" session-start",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" user-prompt-submit",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" post-tool-use",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" pre-compact",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs\" session-end",
+            "timeout": 8
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run.mjs

@@ -0,0 +1,88 @@
+// The plugin's hook launcher. Node builtins only, on purpose.
+//
+// The plugin and the CLI ship separately: skills and this file come from the
+// plugin, and everything that touches the database comes from the CLI, which npm
+// installs with its native storage engine. So a hook cannot do the work itself,
+// and it must not need the engine to exist in order to run.
+//
+// Pointing hooks.json straight at `superdev hook <event>` almost works. What it
+// gets wrong is the case that matters most: somebody who installed the plugin
+// and not the CLI sees `sh: superdev: command not found` in their harness, which
+// says nothing about what to install or why. A first impression should not be a
+// shell error.
+//
+// So this launcher sits in between. It finds the CLI and hands over, or it
+// returns a valid hook response saying exactly what to install. Either way the
+// harness gets well-formed output and the session continues, because a hook that
+// breaks a session is worse than a hook that does nothing.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+const EVENT = process.argv[2] ?? "";
+
+/** Hook events that can carry text back to the agent. */
+const CONTEXT_EVENTS = new Set(["SessionStart", "UserPromptSubmit"]);
+
+const EVENT_NAMES = {
+  "session-start": "SessionStart",
+  "user-prompt-submit": "UserPromptSubmit",
+  "post-tool-use": "PostToolUse",
+  "pre-compact": "PreCompact",
+  "session-end": "SessionEnd",
+};
+
+/**
+ * Where the CLI would be if it is installed.
+ *
+ * PATH is searched by hand rather than trusting the shell, because a harness may
+ * run this with a PATH that does not include a user's npm prefix, and the answer
+ * "not installed" is very different from "installed somewhere I did not look".
+ */
+function findCli() {
+  const name = process.platform === "win32" ? "superdev.cmd" : "superdev";
+  const extra = [
+    join(process.env.HOME ?? "", ".local", "bin"),
+    join(process.env.HOME ?? "", ".npm-global", "bin"),
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+  ];
+  for (const dir of [...(process.env.PATH ?? "").split(delimiter), ...extra]) {
+    if (!dir) continue;
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** A response the harness will accept, whatever went wrong. */
+function respond(text) {
+  const hookEventName = EVENT_NAMES[EVENT] ?? EVENT;
+  if (text && CONTEXT_EVENTS.has(hookEventName)) {
+    process.stdout.write(`${JSON.stringify({
+      hookSpecificOutput: { hookEventName, additionalContext: text },
+      suppressOutput: true,
+    })}\n`);
+  } else {
+    process.stdout.write("{}\n");
+  }
+  process.exit(0);
+}
+
+const cli = findCli();
+if (!cli) {
+  respond([
+    "Superdev: the plugin is installed and its command-line tool is not, so nothing can read or write the project record.",
+    "Install it with: npm install -g superdev-cli",
+    "The plugin carries the skills; the CLI carries the database engine, which npm installs for your platform. Nothing else is needed.",
+  ].join("\n"));
+}
+
+// Hand over completely: same stdin, same stdout, same exit code. From here the
+// CLI owns the hook contract and this file has no further opinion about it.
+const child = spawn(cli, ["hook", EVENT], { stdio: "inherit" });
+child.on("error", () => respond(
+  "Superdev: its command-line tool was found but could not be started. Check that npm install -g superdev-cli completed, then run superdev --version.",
+));
+child.on("close", (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "superdev-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local-first product-building control system for humans and coding agents.",
+  "author": "Rahul Retnan",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdev-ai/superdev.git"
+  },
+  "homepage": "https://github.com/superdev-ai/superdev#readme",
+  "bugs": {
+    "url": "https://github.com/superdev-ai/superdev/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "superdev": "src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "!src/**/*.test.mjs",
+    "skills/",
+    "references/",
+    "hooks/",
+    "scripts/validate/",
+    "!scripts/**/*.test.mjs",
+    "scripts/doctor/",
+    "scripts/privacy/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tursodatabase/database": "0.7.1"
+  },
+  "scripts": {
+    "validate": "node scripts/validate/validate-all.mjs",
+    "scan": "node scripts/privacy/scan.mjs --allow-binary .superdev-scan-binary-allow",
+    "scan:history": "node scripts/privacy/scan-history.mjs --allow-binary .superdev-scan-binary-allow --history-allow .superdev-scan-history-allow",
+    "ui:build": "node scripts/package/build-ui.mjs build",
+    "ui:check": "node scripts/package/build-ui.mjs check",
+    "prepublishOnly": "npm test && node scripts/validate/validate-all.mjs && node scripts/package/build-ui.mjs check",
+    "release": "npm run release:tooling && npx release-it",
+    "release:patch": "npm run release:tooling && npx release-it patch",
+    "release:minor": "npm run release:tooling && npx release-it minor",
+    "release:major": "npm run release:tooling && npx release-it major",
+    "release:dry": "npm run release:tooling && npx release-it --dry-run",
+    "version:sync": "node scripts/package/sync-version.mjs --apply",
+    "check": "npm test && node scripts/validate/validate-all.mjs && node src/cli.mjs doctor && node scripts/check/release-criteria.mjs",
+    "release:tooling": "npm install --no-save --silent release-it@19 @release-it/conventional-changelog@10",
+    "test": "node --test \"src/**/*.test.mjs\""
+  }
+}

package/references/confidentiality.md

@@ -0,0 +1,48 @@
+# Confidentiality and Leak-Prevention Policy
+
+Superdev is developed with a strict private/public boundary: private development evidence informs the design, but no private identifier, path, or recognizable material may appear in this repository, its git history, tests, fixtures, generated artifacts, or release archives. This document describes the public mechanism; the actual denylist lives outside the repository by design.
+
+## The leak scanner
+
+`scripts/privacy/scan.mjs` scans file contents and relative paths for:
+
+- entries from an **external denylist** supplied at execution time (`--denylist <path>`) - the denylist itself is never shipped, committed, or echoed into scanner output; findings reference rule ids (`DL-<n>`) and file/line locations only;
+- absolute home-directory paths (`/Users/<name>/…`, `/home/<name>/…`);
+- email addresses outside documentation-safe example domains;
+- private-key markers and high-entropy secret-like strings;
+- environment files staged for commit.
+
+Behavior contract: reads only; writes nothing unless `--out <path>` is explicitly provided; machine-readable JSON on stdout with `--json`; exit `0` clean, `1` findings, `2` usage error. Any finding - P0 or P1 - is release-blocking: the scanner exits non-zero on either, and packaging, publication, and pushes stop until resolved.
+
+One documented allowlist exception: `anthropic.com` addresses pass the email rule because agent-generated commits carry standard `Co-Authored-By` trailers that history scans would otherwise flag.
+
+## Where the gates run
+
+| Gate | When |
+|---|---|
+| Denylist + built-in scans over the working tree | before every commit |
+| Scan over staged files (`--staged`) | before every commit |
+| Archive listing + content scan | every package build |
+| Full git-history scan | before any first public push |
+| Cross-product re-identifiability review (below) | before release |
+
+## Synthetic fixtures
+
+Current tests generate their fixture material at runtime inside temporary directories. Any fixture added to the repository (e.g. under `tests/fixtures/`) must be independently authored and synthetic:
+
+- generic domains only (e.g. `sample-saas`, `sample-mobile-app`, `legacy-docs-project`, `module-docs-project`, `example-api`);
+- deliberately fictional feature combinations, counts, names, routes, schemas, and stacks;
+- fictional far-future dates;
+- a provenance note declaring the fixture independently authored.
+
+Renaming something real is not anonymization: a fixture that preserves a real project's recognizable vertical, route shapes, counts, schema, or wording fails review even with every name changed.
+
+## Cross-product re-identifiability review
+
+Before release, review whether multiple individually-generic examples **combine** to identify any real system (same module mix + same workflow shape + same domain vocabulary). If they do, replace with broader composites. Reviewer output is recorded as release evidence.
+
+## Contributor rules
+
+- Never commit real project names, client names, internal domains, local paths, package scopes, or credentials - in code, fixtures, tests, comments, or commit messages.
+- Never paste real error logs or screenshots without redaction.
+- Treat any leak as an incident: stop, remove, rescan; if it entered git history, the history is rebuilt or sanitized before any publication.