vibe-coding-master 0.4.1 → 0.4.3

package/README.md

@@ -30,7 +30,7 @@ When Gate Review Gates are enabled for a task, or when a Gate Reviewer session a
 - Manual and automatic orchestration modes.
 - Two-stage VCM harness setup: deterministic fixed install plus AI-assisted bootstrap.
 - VCM-managed root rules, role agents, repo-local VCM skills, Claude Code hooks, generated-context tools, and PR template.
-- Rust generated context for module indexing and crate-external public surface indexing.
+- Generated context for Rust and npm workspace module indexing plus public surface indexing.
 - Translation panel powered by the long-lived Translator session.
 - Mobile Gateway through Tencent iLink Bot API / Weixin DM, for talking to PM and managing tasks from Weixin.
 - Durable task state, role session state, handoff artifacts, and message history.
@@ -497,7 +497,7 @@ docs/TESTING.md
 .ai/generated/public-surface.json
 ```
 
-The generated-context tools currently target Rust projects. Non-Rust repositories can still install the fixed harness, but generated context should be treated as unsupported until project-specific generators exist.
+The generated-context tools support Rust/Cargo projects and npm workspace TypeScript/JavaScript projects. Other repository shapes can still install the fixed harness, but generated context should be treated as unsupported until project-specific generators exist.
 
 After applying harness changes or completing bootstrap, VCM reports the exact files changed or checks completed and reminds the user to review and commit them before starting long-running work.
 

package/dist/backend/cli/install-vcm-harness.js

@@ -314,7 +314,7 @@ Installs only fixed VCM harness content.
 This deterministic installer handles VCM-owned managed blocks, VCM-owned whole
 files, VCM Claude settings hooks, generic long-running helper tools, and the
 harness manifest. It also creates blank durable project doc templates when
-missing and installs Rust generated-context generator tools. It does not copy
+missing and installs generated-context tools for Rust and npm workspace projects. It does not copy
 example project docs, generated context artifacts, module-level architecture
 docs, or task runtime handoff artifacts.`);
 }

package/dist/backend/services/message-service.js

@@ -1,13 +1,10 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { CORE_VCM_ROLE_NAMES } from "../../shared/constants.js";
-import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { renderMessageEnvelope } from "../templates/message-envelope.js";
 const PM_ROLE = "project-manager";
-const PM_TO_ROLE_TYPES = new Set(["task", "question", "review-request", "revise", "cancel"]);
-const ROLE_TO_PM_TYPES = new Set(["result", "question", "blocked", "finding"]);
 const DEFAULT_PRE_DISPATCH_SWITCH_DELAY_MS = 500;
 const DEFAULT_AUTO_DISPATCH_ENTER_DELAY_MS = 500;
 const DEFAULT_DISPATCH_CONFIRMATION_RETRY_DELAYS_MS = [1500, 3000];
@@ -64,7 +61,6 @@ export function createMessageService(deps) {
         return all.filter((routeFile) => routeFile.pending);
     }
     async function dispatchRouteFile(input, routeFile, state, timestamp) {
-        validateMessagePolicy(routeFile.fromRole, routeFile.toRole, routeFile.type);
         const session = await deps.sessionService.getRoleSession(input.repoRoot, input.taskSlug, routeFile.toRole);
         if (!session || session.status !== "running") {
             return {
@@ -370,34 +366,6 @@ function selectDispatchCandidates(routeFiles, stoppedRole) {
         return updated !== 0 ? updated : left.path.localeCompare(right.path);
     });
 }
-function validateMessagePolicy(fromRole, toRole, type) {
-    if (!CORE_VCM_ROLE_NAMES.some((role) => role === toRole)) {
-        throw new VcmError({
-            code: "MESSAGE_TARGET_UNKNOWN",
-            message: `Unknown target role: ${toRole}`,
-            statusCode: 400
-        });
-    }
-    if (!CORE_VCM_ROLE_NAMES.some((role) => role === fromRole)) {
-        throw new VcmError({
-            code: "MESSAGE_SENDER_UNKNOWN",
-            message: `Unknown sender role: ${fromRole}`,
-            statusCode: 400
-        });
-    }
-    if (fromRole === PM_ROLE && toRole !== PM_ROLE && PM_TO_ROLE_TYPES.has(type)) {
-        return;
-    }
-    if (fromRole !== PM_ROLE && toRole === PM_ROLE && ROLE_TO_PM_TYPES.has(type)) {
-        return;
-    }
-    throw new VcmError({
-        code: "MESSAGE_POLICY_DENIED",
-        message: `${fromRole} cannot send ${type} messages to ${toRole}.`,
-        statusCode: 403,
-        hint: "Use project-manager as the orchestration hub unless this task explicitly allows a peer route."
-    });
-}
 async function withTaskLock(locks, key, run) {
     const previous = locks.get(key) ?? Promise.resolve();
     const next = previous.catch(() => undefined).then(run);

package/dist/backend/templates/harness/architect-agent.js

@@ -80,7 +80,7 @@ export function renderArchitectHarnessRules() {
 - Update affected \`<module>/ARCHITECTURE.md\` when module-level detailed design changes: boundaries, behavior, important public surface explanations, internal risks, or module-specific architecture notes.
 - Treat \`.ai/generated/public-surface.json\` as the full machine index for public surface. Verify or report its freshness when public APIs changed; do not replace it with prose in architecture docs.
 - When module structure changes, require \`.ai/tools/generate-module-index --check\` or regeneration.
-- When crate-external public APIs change, require \`.ai/tools/generate-public-surface --check\` or regeneration.
+- When public APIs, routes, or externally consumed surfaces change, require \`.ai/tools/generate-public-surface --check\` or regeneration.
 - Read \`.ai/vcm/handoffs/known-issues.md\` and promote confirmed unresolved issues to \`docs/known-issues.md\`.
 - Write \`.ai/vcm/handoffs/docs-sync-report.md\` with decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, remaining documentation risks, and handoff notes.
 

package/dist/backend/templates/harness/claude-root.js

@@ -22,7 +22,7 @@ export function renderRootClaudeHarnessRules() {
 - \`docs/TESTING.md\`: validation strategy, commands, validation levels, integration/E2E case definitions, final-validation cleanup, and known testing gaps; reviewer-owned.
 - \`docs/known-issues.md\`: durable known issues and accepted limitations; architect-owned.
 - \`.ai/generated/module-index.json\`: generated module index; use it to find layers, modules, manifests, module docs, source files, test files, and workspace dependencies.
-- \`.ai/generated/public-surface.json\`: generated crate-external public API index; use it to inspect module-to-module public interfaces and source evidence.
+- \`.ai/generated/public-surface.json\`: generated public surface index; use it to inspect module-to-module public APIs, routes, and source evidence.
 
 ## VCM Task Flow
 

package/dist/backend/templates/harness/coder-agent.js

@@ -48,7 +48,7 @@ export function renderCoderHarnessRules() {
 ### Generated Context
 
 - Regenerate \`.ai/generated/module-index.json\` with \`.ai/tools/generate-module-index\` after module, manifest, source-file, or test-file changes.
-- Regenerate \`.ai/generated/public-surface.json\` with \`.ai/tools/generate-public-surface\` after crate-external public API or public visibility changes.
+- Regenerate \`.ai/generated/public-surface.json\` with \`.ai/tools/generate-public-surface\` after public API, route, externally consumed surface, or public visibility changes.
 - Do not hand-edit generated context files.
 
 ### Baseline Tests

package/dist/backend/templates/harness/vcm-harness-bootstrap-skill.js

@@ -49,7 +49,7 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 
 - Document the project-level module overview, module responsibilities, module relationships, dependency direction, and project-wide constraints.
 - Link to module-level \`ARCHITECTURE.md\` files when present.
-- Explain generated-context ownership, especially that \`.ai/generated/public-surface.json\` is the machine index for crate-external public APIs.
+- Explain generated-context ownership, especially that \`.ai/generated/public-surface.json\` is the machine index for public APIs, routes, and externally consumed surfaces.
 
 ### Module-Level \`ARCHITECTURE.md\`
 

package/docs/full-harness-baseline.md

@@ -101,10 +101,10 @@ Directory roots created by the installer:
 .ai/tools/vcm-bash-guard
 ```
 
-`generate-module-index` and `generate-public-surface` currently target Rust
-projects. Non-Rust repositories can still install the fixed harness, but
-generated context should be treated as unsupported until project-specific
-generators exist.
+`generate-module-index` and `generate-public-surface` support Rust/Cargo
+projects and npm workspace TypeScript/JavaScript projects. Other repository
+shapes can still install the fixed harness, but generated context should be
+treated as unsupported until project-specific generators exist.
 
 ## Runtime State
 

package/docs/vcm-cc-best-practices.md

@@ -363,13 +363,12 @@ The current example has two generated artifacts:
 `module-index.json` helps agents find layers, modules, manifests, module docs,
 source files, test files, and workspace dependencies.
 
-`public-surface.json` indexes crate-external Rust public APIs. It is a machine
-index, not an architecture document.
+`public-surface.json` indexes project public APIs, routes, and externally
+consumed surfaces. It is a machine index, not an architecture document.
 
-Current generated-context support is Rust-only. The fixed installer provides
-Rust generator tools as the default baseline, but it does not generate trusted
-context by itself. Non-Rust projects must use project-specific generators before
-`.ai/generated/*` is considered reliable.
+Current generated-context support covers Rust/Cargo projects and npm workspace
+TypeScript/JavaScript projects. Other repository shapes must use
+project-specific generators before `.ai/generated/*` is considered reliable.
 
 There is no `test-map.json`. Rust unit tests live with source where appropriate;
 integration tests use Cargo's normal test layout. Test files are discoverable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/clean-build.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 const root = process.cwd();
-const buildDirs = ["dist", "dist-frontend"];
+const buildDirs = ["dist", "dist-frontend", "scripts/harness-tools/__pycache__"];
 
 await Promise.all(buildDirs.map((dir) => {
   return fs.rm(path.join(root, dir), {

package/scripts/harness-tools/generate-module-index

@@ -12,6 +12,12 @@ except ModuleNotFoundError:
     tomllib = None
 
 
+NODE_SOURCE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs")
+NODE_EXCLUDED_DIRS = {"node_modules", "dist", "build", "coverage", ".next", ".turbo", ".vite"}
+NODE_DEPENDENCY_TABLES = ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies")
+NODE_TEST_MARKERS = (".test.", ".spec.")
+
+
 def relative_path(path: Path, root: Path) -> str:
     try:
         rel = path.absolute().relative_to(root.absolute())
@@ -20,7 +26,7 @@ def relative_path(path: Path, root: Path) -> str:
     return "." if str(rel) == "." else rel.as_posix()
 
 
-def find_cargo_root(project_root: Path) -> Path:
+def maybe_find_cargo_root(project_root: Path) -> Path | None:
     if (project_root / "Cargo.toml").is_file():
         return project_root
 
@@ -28,7 +34,18 @@ def find_cargo_root(project_root: Path) -> Path:
         if child.is_dir() and (child / "Cargo.toml").is_file():
             return child
 
-    raise SystemExit(f"Could not find Cargo.toml in {project_root} or its direct child directories.")
+    return None
+
+
+def find_cargo_root(project_root: Path) -> Path:
+    cargo_root = maybe_find_cargo_root(project_root)
+    if cargo_root is None:
+        raise SystemExit(f"Could not find Cargo.toml in {project_root} or its direct child directories.")
+    return cargo_root
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text())
 
 
 def load_toml(path: Path) -> dict:
@@ -149,6 +166,196 @@ def rust_files_under(module_dir: Path, project_root: Path, child: str) -> list[s
     )
 
 
+def maybe_find_node_root(project_root: Path) -> Path | None:
+    if (project_root / "package.json").is_file():
+        return project_root
+
+    for child in sorted(project_root.iterdir(), key=lambda path: path.name):
+        if child.is_dir() and (child / "package.json").is_file():
+            return child
+
+    return None
+
+
+def workspace_patterns(package_data: dict) -> list[str]:
+    workspaces = package_data.get("workspaces")
+    if isinstance(workspaces, list):
+        return [pattern for pattern in workspaces if isinstance(pattern, str)]
+    if isinstance(workspaces, dict):
+        packages = workspaces.get("packages", [])
+        if isinstance(packages, list):
+            return [pattern for pattern in packages if isinstance(pattern, str)]
+    return []
+
+
+def node_workspace_manifests(node_root: Path) -> list[Path]:
+    root_manifest = node_root / "package.json"
+    root_data = load_json(root_manifest)
+    patterns = workspace_patterns(root_data)
+
+    if not patterns:
+        return [root_manifest]
+
+    manifests: list[Path] = []
+    seen: set[Path] = set()
+
+    for pattern in patterns:
+        if pattern.startswith("!") or pattern.startswith("/") or ".." in Path(pattern).parts:
+            continue
+        for candidate in sorted(node_root.glob(pattern), key=lambda path: path.as_posix()):
+            manifest = candidate / "package.json"
+            if not candidate.is_dir() or not manifest.is_file() or manifest in seen:
+                continue
+            if any(part in NODE_EXCLUDED_DIRS for part in relative_path(candidate, node_root).split("/")):
+                continue
+            manifests.append(manifest)
+            seen.add(manifest)
+
+    if root_data.get("name") and (root_data.get("main") or root_data.get("exports") or (node_root / "src").is_dir()):
+        manifests.insert(0, root_manifest)
+
+    return manifests
+
+
+def node_dependency_names(manifest: Path) -> set[str]:
+    data = load_json(manifest)
+    names: set[str] = set()
+    for table_name in NODE_DEPENDENCY_TABLES:
+        table = data.get(table_name, {})
+        if isinstance(table, dict):
+            names.update(name for name in table.keys() if isinstance(name, str))
+    return names
+
+
+def node_source_files_under(module_dir: Path, project_root: Path) -> tuple[list[str], list[str]]:
+    source_root = module_dir / "src"
+    if not source_root.is_dir():
+        return ([], [])
+
+    source_files: list[str] = []
+    test_files: list[str] = []
+
+    for path in sorted(source_root.rglob("*"), key=lambda item: item.as_posix()):
+        if not path.is_file():
+            continue
+        if path.suffix not in NODE_SOURCE_EXTENSIONS or path.name.endswith(".d.ts"):
+            continue
+        if any(part in NODE_EXCLUDED_DIRS for part in path.relative_to(module_dir).parts):
+            continue
+
+        rel = relative_path(path, project_root)
+        if any(marker in path.name for marker in NODE_TEST_MARKERS):
+            test_files.append(rel)
+        else:
+            source_files.append(rel)
+
+    tests_root = module_dir / "tests"
+    if tests_root.is_dir():
+        for path in sorted(tests_root.rglob("*"), key=lambda item: item.as_posix()):
+            if (
+                path.is_file()
+                and path.suffix in NODE_SOURCE_EXTENSIONS
+                and not path.name.endswith(".d.ts")
+                and not any(part in NODE_EXCLUDED_DIRS for part in path.relative_to(module_dir).parts)
+            ):
+                test_files.append(relative_path(path, project_root))
+
+    return (source_files, sorted(set(test_files)))
+
+
+def infer_node_layer(module_path: str, node_root: Path, project_root: Path) -> tuple[str, str]:
+    node_root_rel = relative_path(node_root, project_root)
+    if module_path == node_root_rel:
+        return ("root", node_root_rel)
+
+    relative_to_node_root = relative_path(project_root / module_path, node_root)
+    first = relative_to_node_root.split("/", 1)[0]
+    return (first, relative_path(node_root / first, project_root))
+
+
+def node_package_records(node_root: Path) -> list[dict]:
+    manifests = node_workspace_manifests(node_root)
+    records: list[dict] = []
+    names_by_manifest: dict[Path, str] = {}
+
+    for manifest in manifests:
+        data = load_json(manifest)
+        name = data.get("name")
+        if isinstance(name, str) and name:
+            names_by_manifest[manifest] = name
+
+    workspace_names = set(names_by_manifest.values())
+
+    for manifest, name in names_by_manifest.items():
+        dependency_names = node_dependency_names(manifest) & workspace_names
+        records.append(
+            {
+                "name": name,
+                "manifest": manifest,
+                "workspaceDependencies": sorted(dependency_names),
+            }
+        )
+
+    return records
+
+
+def build_node_index(project_root: Path, node_root: Path) -> dict:
+    records = node_package_records(node_root)
+    has_workspaces = bool(workspace_patterns(load_json(node_root / "package.json")))
+    layers: list[dict] = []
+    layer_by_name: dict[str, dict] = {}
+
+    for record in records:
+        manifest_path = record["manifest"]
+        module_dir = manifest_path.parent
+        module_path = relative_path(module_dir, project_root)
+        manifest_rel = relative_path(manifest_path, project_root)
+        layer_name, layer_path = infer_node_layer(module_path, node_root, project_root)
+        source_files, test_files = node_source_files_under(module_dir, project_root)
+
+        if layer_name not in layer_by_name:
+            layer = {
+                "name": layer_name,
+                "path": layer_path,
+                "modules": [],
+            }
+            layer_by_name[layer_name] = layer
+            layers.append(layer)
+
+        layer_by_name[layer_name]["modules"].append(
+            {
+                "name": record["name"],
+                "path": module_path,
+                "manifest": manifest_rel,
+                "architectureDoc": f"{module_path}/ARCHITECTURE.md"
+                if module_path != "."
+                else "ARCHITECTURE.md",
+                "workspaceDependencies": record["workspaceDependencies"],
+                "language": "typescript",
+                "files": {
+                    "source": source_files,
+                    "tests": test_files,
+                },
+            }
+        )
+
+    return {
+        "schemaVersion": 1,
+        "kind": "module-index",
+        "generatedBy": ".ai/tools/generate-module-index",
+        "workspace": {
+            "type": "npm-workspaces" if has_workspaces else "npm-package",
+            "root": relative_path(node_root, project_root),
+            "manifest": relative_path(node_root / "package.json", project_root),
+        },
+        "layerInference": {
+            "method": "path-first-segment-from-workspace-root",
+            "rootPackageLayer": "root",
+        },
+        "layers": layers,
+    }
+
+
 def package_records_from_metadata(project_root: Path, cargo_root: Path, metadata: dict) -> list[dict]:
     workspace_root = Path(metadata["workspace_root"])
     workspace_member_ids = set(metadata["workspace_members"])
@@ -201,8 +408,7 @@ def package_records_from_manifests(cargo_root: Path) -> list[dict]:
     return records
 
 
-def build_index(project_root: Path) -> dict:
-    cargo_root = find_cargo_root(project_root)
+def build_cargo_index(project_root: Path, cargo_root: Path) -> dict:
     metadata = load_cargo_metadata(cargo_root)
     records = (
         package_records_from_metadata(project_root, cargo_root, metadata)
@@ -262,8 +468,22 @@ def build_index(project_root: Path) -> dict:
     }
 
 
+def build_index(project_root: Path) -> dict:
+    cargo_root = maybe_find_cargo_root(project_root)
+    if cargo_root is not None:
+        return build_cargo_index(project_root, cargo_root)
+
+    node_root = maybe_find_node_root(project_root)
+    if node_root is not None:
+        return build_node_index(project_root, node_root)
+
+    raise SystemExit(
+        f"Could not find Cargo.toml or package.json in {project_root} or its direct child directories."
+    )
+
+
 def main() -> int:
-    parser = argparse.ArgumentParser(description="Generate .ai/generated/module-index.json from cargo metadata.")
+    parser = argparse.ArgumentParser(description="Generate .ai/generated/module-index.json from Cargo or npm workspace metadata.")
     parser.add_argument("--check", action="store_true", help="Fail if the generated module index differs from the current file.")
     parser.add_argument("--print", action="store_true", help="Print generated JSON instead of writing it.")
     parser.add_argument("--output", default=".ai/generated/module-index.json", help="Output path relative to the project root.")

package/scripts/harness-tools/generate-public-surface

@@ -23,6 +23,20 @@ BLOCK_ITEM_KEYWORDS = {
     "union",
     "macro_rules",
 }
+TS_SOURCE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs")
+TS_EXPORT_DECLARATION = re.compile(
+    r"\bexport\s+(?:default\s+)?(?:declare\s+)?(?:(?:async\s+)?function\s+(?P<function>[A-Za-z_$][A-Za-z0-9_$]*)|class\s+(?P<class>[A-Za-z_$][A-Za-z0-9_$]*)|interface\s+(?P<interface>[A-Za-z_$][A-Za-z0-9_$]*)|type\s+(?P<type>[A-Za-z_$][A-Za-z0-9_$]*)|enum\s+(?P<enum>[A-Za-z_$][A-Za-z0-9_$]*)|(?:const|let|var)\s+(?P<variable>[A-Za-z_$][A-Za-z0-9_$]*))"
+)
+TS_REEXPORT = re.compile(
+    r"\bexport\s+(?:type\s+)?(?P<form>\*|\{[^}]*\})\s+from\s+(?P<quote>[\"'`])(?P<specifier>[^\"'`]+)(?P=quote)"
+)
+TS_ROUTE_CALL = re.compile(
+    r"\.\s*(?P<method>get|post|put|patch|delete|options|head)\s*\(\s*(?P<quote>[\"'`])(?P<path>[^\"'`]+)(?P=quote)",
+    re.IGNORECASE,
+)
+TS_ROUTE_OBJECT = re.compile(r"\.route\s*\(\s*\{(?P<body>.*?)\}\s*\)", re.IGNORECASE | re.DOTALL)
+TS_ROUTE_METHOD = re.compile(r"\bmethod\s*:\s*(?P<quote>[\"'`])(?P<method>[A-Za-z]+)(?P=quote)", re.IGNORECASE)
+TS_ROUTE_URL = re.compile(r"\b(?:url|path)\s*:\s*(?P<quote>[\"'`])(?P<path>[^\"'`]+)(?P=quote)", re.IGNORECASE)
 
 
 @dataclass(frozen=True)
@@ -56,6 +70,24 @@ def load_module_index(root: Path) -> dict:
     return json.loads(path.read_text())
 
 
+def load_optional_json(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    return json.loads(path.read_text())
+
+
+def relative_path(path: Path, root: Path) -> str:
+    try:
+        rel = path.absolute().relative_to(root.absolute())
+    except ValueError:
+        rel = path.resolve().relative_to(root.resolve())
+    return "." if str(rel) == "." else rel.as_posix()
+
+
+def line_number_from_offset(source: str, offset: int) -> int:
+    return source.count("\n", 0, offset) + 1
+
+
 def raw_string_end(source: str, index: int) -> int | None:
     for prefix in ("br", "rb", "r"):
         if not source.startswith(prefix, index):
@@ -633,13 +665,366 @@ def extract_public_items(root: Path, module: dict) -> list[dict]:
     return unique_items
 
 
+def remove_ts_comments_preserve_literals(source: str) -> str:
+    output: list[str] = []
+    cursor = 0
+    quote: str | None = None
+    escaped = False
+
+    while cursor < len(source):
+        char = source[cursor]
+
+        if quote is not None:
+            output.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+            cursor += 1
+            continue
+
+        if source.startswith("//", cursor):
+            end = source.find("\n", cursor + 2)
+            if end == -1:
+                output.append(" " * (len(source) - cursor))
+                break
+            output.append(" " * (end - cursor))
+            output.append("\n")
+            cursor = end + 1
+            continue
+
+        if source.startswith("/*", cursor):
+            end = source.find("*/", cursor + 2)
+            end = len(source) if end == -1 else end + 2
+            chunk = source[cursor:end]
+            output.append("".join("\n" if item == "\n" else " " for item in chunk))
+            cursor = end
+            continue
+
+        if char in {"'", '"', "`"}:
+            quote = char
+            escaped = False
+            output.append(char)
+            cursor += 1
+            continue
+
+        output.append(char)
+        cursor += 1
+
+    return "".join(output)
+
+
+def ts_signature_from_source(source: str, start: int) -> str:
+    cursor = start
+    depth_angle = 0
+    depth_paren = 0
+    depth_bracket = 0
+
+    while cursor < len(source):
+        char = source[cursor]
+        if char in {"'", '"', "`"}:
+            cursor = quoted_literal_end(source, cursor) if char != "`" else quoted_literal_end(source.replace("`", '"'), cursor)
+            continue
+
+        if char == "<":
+            depth_angle += 1
+        elif char == ">" and depth_angle:
+            depth_angle -= 1
+        elif char == "(":
+            depth_paren += 1
+        elif char == ")" and depth_paren:
+            depth_paren -= 1
+        elif char == "[":
+            depth_bracket += 1
+        elif char == "]" and depth_bracket:
+            depth_bracket -= 1
+
+        at_top_level = depth_angle == 0 and depth_paren == 0 and depth_bracket == 0
+        if at_top_level and char in "{;":
+            return " ".join(source[start:cursor].split())
+        cursor += 1
+
+    return " ".join(source[start:].split())
+
+
+def ts_item_kind(match: re.Match) -> tuple[str, str] | None:
+    for kind in ("function", "class", "interface", "type", "enum", "variable"):
+        name = match.group(kind)
+        if name:
+            return ("const" if kind == "variable" else kind, name)
+    return None
+
+
+def extract_ts_exported_declarations(source: str, source_file: str) -> list[dict]:
+    sanitized = remove_ts_comments_preserve_literals(source)
+    items: list[dict] = []
+
+    for match in TS_EXPORT_DECLARATION.finditer(sanitized):
+        kind_and_name = ts_item_kind(match)
+        if kind_and_name is None:
+            continue
+        kind, name = kind_and_name
+        items.append(
+            {
+                "path": name,
+                "kind": kind,
+                "name": name,
+                "source": {
+                    "path": source_file,
+                    "line": line_number_from_offset(sanitized, match.start()),
+                },
+                "signature": ts_signature_from_source(source, match.start()),
+            }
+        )
+
+    return items
+
+
+def exported_names_from_group(group: str) -> list[tuple[str, str]]:
+    names: list[tuple[str, str]] = []
+    body = group.strip()[1:-1]
+    for raw_part in body.split(","):
+        part = raw_part.strip()
+        if not part:
+            continue
+        if part.startswith("type "):
+            part = part.removeprefix("type ").strip()
+        pieces = [piece.strip() for piece in re.split(r"\s+as\s+", part, maxsplit=1)]
+        source_name = pieces[0]
+        public_name = pieces[1] if len(pieces) == 2 else source_name
+        if source_name and source_name != "default":
+            names.append((source_name, public_name))
+    return names
+
+
+def resolve_ts_specifier(current_file: Path, specifier: str, indexed_sources: dict[Path, str]) -> str | None:
+    if not specifier.startswith("."):
+        return None
+
+    base = (current_file.parent / specifier).resolve()
+    candidates: list[Path] = []
+
+    if base.suffix:
+        candidates.append(base)
+        for extension in TS_SOURCE_EXTENSIONS:
+            candidates.append(base.with_suffix(extension))
+    else:
+        for extension in TS_SOURCE_EXTENSIONS:
+            candidates.append(base.with_suffix(extension))
+        for extension in TS_SOURCE_EXTENSIONS:
+            candidates.append(base / f"index{extension}")
+
+    for candidate in candidates:
+        source_file = indexed_sources.get(candidate.resolve())
+        if source_file is not None:
+            return source_file
+
+    return None
+
+
+def package_export_targets(value) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        targets: list[str] = []
+        for item in value:
+            targets.extend(package_export_targets(item))
+        return targets
+    if isinstance(value, dict):
+        targets: list[str] = []
+        for key, item in value.items():
+            if key in {"types", "import", "require", "default", "module"} or key.startswith("."):
+                targets.extend(package_export_targets(item))
+        return targets
+    return []
+
+
+def ts_entrypoint_files(root: Path, module: dict) -> list[str]:
+    indexed_sources = set(module.get("files", {}).get("source", []))
+    module_path = module.get("path", ".")
+    module_root = root if module_path == "." else root / module_path
+    manifest = load_optional_json(root / module.get("manifest", ""))
+    targets: list[str] = []
+
+    for key in ("exports", "main", "module", "types"):
+        targets.extend(package_export_targets(manifest.get(key)))
+
+    candidates: list[str] = []
+    for target in targets:
+        if not isinstance(target, str):
+            continue
+        target_path = (module_root / target).resolve()
+        for candidate in [target_path, *[target_path.with_suffix(ext) for ext in TS_SOURCE_EXTENSIONS]]:
+            rel = relative_path(candidate, root)
+            if rel in indexed_sources:
+                candidates.append(rel)
+
+    if not candidates:
+        for name in ("index", "main", "app"):
+            for extension in TS_SOURCE_EXTENSIONS:
+                rel = relative_path(module_root / "src" / f"{name}{extension}", root)
+                if rel in indexed_sources:
+                    candidates.append(rel)
+
+    if not candidates and module_path.startswith("apps/"):
+        candidates.extend(module.get("files", {}).get("source", []))
+
+    return sorted(dict.fromkeys(candidates))
+
+
+def collect_ts_public_items(
+    root: Path,
+    source_file: str,
+    module: dict,
+    direct_definitions: dict[str, dict[str, dict]],
+    indexed_sources: dict[Path, str],
+    visited: set[str],
+) -> list[dict]:
+    if source_file in visited:
+        return []
+    visited.add(source_file)
+
+    path = root / source_file
+    source = path.read_text()
+    sanitized = remove_ts_comments_preserve_literals(source)
+    items = list(direct_definitions.get(source_file, {}).values())
+
+    for match in TS_REEXPORT.finditer(sanitized):
+        target_file = resolve_ts_specifier(path, match.group("specifier"), indexed_sources)
+        if target_file is None:
+            continue
+
+        form = match.group("form")
+        if form == "*":
+            items.extend(collect_ts_public_items(root, target_file, module, direct_definitions, indexed_sources, visited))
+            continue
+
+        target_definitions = direct_definitions.get(target_file, {})
+        for source_name, public_name in exported_names_from_group(form):
+            definition = target_definitions.get(source_name)
+            if definition is None:
+                items.append(
+                    {
+                        "path": public_name,
+                        "kind": "re-export",
+                        "name": public_name,
+                        "source": {
+                            "path": source_file,
+                            "line": line_number_from_offset(sanitized, match.start()),
+                        },
+                    }
+                )
+                continue
+            items.append({**definition, "path": public_name, "name": public_name})
+
+    return items
+
+
+def extract_ts_routes(source: str, source_file: str) -> list[dict]:
+    sanitized = remove_ts_comments_preserve_literals(source)
+    items: list[dict] = []
+
+    for match in TS_ROUTE_CALL.finditer(sanitized):
+        method = match.group("method").upper()
+        route_path = match.group("path")
+        name = f"{method} {route_path}"
+        items.append(
+            {
+                "path": name,
+                "kind": "route",
+                "name": name,
+                "source": {
+                    "path": source_file,
+                    "line": line_number_from_offset(sanitized, match.start()),
+                },
+            }
+        )
+
+    for match in TS_ROUTE_OBJECT.finditer(sanitized):
+        body = match.group("body")
+        method_match = TS_ROUTE_METHOD.search(body)
+        path_match = TS_ROUTE_URL.search(body)
+        if method_match is None or path_match is None:
+            continue
+        name = f"{method_match.group('method').upper()} {path_match.group('path')}"
+        items.append(
+            {
+                "path": name,
+                "kind": "route",
+                "name": name,
+                "source": {
+                    "path": source_file,
+                    "line": line_number_from_offset(sanitized, match.start()),
+                },
+            }
+        )
+
+    return items
+
+
+def extract_typescript_public_items(root: Path, module: dict) -> list[dict]:
+    indexed_sources = {
+        (root / source_file).resolve(): source_file
+        for source_file in module.get("files", {}).get("source", [])
+    }
+    direct_definitions: dict[str, dict[str, dict]] = {}
+
+    for source_file in module.get("files", {}).get("source", []):
+        path = root / source_file
+        if not path.is_file():
+            raise SystemExit(f"Missing source file from module index: {source_file}")
+        direct_definitions[source_file] = {
+            item["name"]: item
+            for item in extract_ts_exported_declarations(path.read_text(), source_file)
+        }
+
+    entrypoints = ts_entrypoint_files(root, module)
+    if not entrypoints:
+        entrypoints = list(module.get("files", {}).get("source", []))
+
+    items: list[dict] = []
+    for entrypoint in entrypoints:
+        items.extend(collect_ts_public_items(root, entrypoint, module, direct_definitions, indexed_sources, set()))
+
+    if module.get("path", "").startswith("apps/"):
+        for source_file in module.get("files", {}).get("source", []):
+            items.extend(extract_ts_routes((root / source_file).read_text(), source_file))
+
+    seen: set[tuple[str, str, str, int]] = set()
+    unique_items: list[dict] = []
+    for item in items:
+        key = (item["path"], item["kind"], item["source"]["path"], item["source"]["line"])
+        if key in seen:
+            continue
+        seen.add(key)
+        unique_items.append(item)
+
+    return unique_items
+
+
+def module_index_is_typescript(module_index: dict) -> bool:
+    workspace = module_index.get("workspace", {})
+    workspace_type = workspace.get("type")
+    if workspace_type in {"npm-workspaces", "npm-package"}:
+        return True
+    manifest = workspace.get("manifest")
+    return isinstance(manifest, str) and manifest.endswith("package.json")
+
+
 def build_surface(root: Path) -> dict:
     module_index = load_module_index(root)
+    is_typescript = module_index_is_typescript(module_index)
     modules = []
 
     for layer in module_index.get("layers", []):
         for module in layer.get("modules", []):
-            public_items = extract_public_items(root, module)
+            public_items = (
+                extract_typescript_public_items(root, module)
+                if is_typescript or module.get("language") == "typescript"
+                else extract_public_items(root, module)
+            )
             modules.append(
                 {
                     "name": module["name"],
@@ -651,13 +1036,13 @@ def build_surface(root: Path) -> dict:
         "schemaVersion": 1,
         "kind": "public-surface",
         "generatedBy": ".ai/tools/generate-public-surface",
-        "visibility": "crate-external",
+        "visibility": "project-public" if is_typescript else "crate-external",
         "modules": modules,
     }
 
 
 def main() -> int:
-    parser = argparse.ArgumentParser(description="Generate .ai/generated/public-surface.json from Rust source files.")
+    parser = argparse.ArgumentParser(description="Generate .ai/generated/public-surface.json from Rust or TypeScript source files.")
     parser.add_argument("--check", action="store_true", help="Fail if the generated public surface differs from the current file.")
     parser.add_argument("--print", action="store_true", help="Print generated JSON instead of writing it.")
     parser.add_argument("--output", default=".ai/generated/public-surface.json", help="Output path relative to the project root.")