askmiyagi 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# Ask Miyagi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A voice tutor for codebases. Ask a question out loud; Miyagi explains by voice while it opens files and highlights the exact code it is talking about, step by step, like a teacher sitting beside you.
+
+Everything runs locally: one command starts a server on `127.0.0.1` and opens the browser. The voice is local by default (ElevenLabs is opt-in), and the model only gets read-only tools.
+
+> Status: early development. See `docs/PLAN.md` for what is built and what is next.
+
+## Use
+
+```sh
+npx askmiyagi path/to/your/repo
+```
+
+Requires Node 24+ and a logged-in [Claude Code](https://claude.com/claude-code) CLI (other providers are planned).
+
+## Develop
+
+```sh
+mise install
+npm ci
+mise exec -- lefthook install
+```
+
+`mise install` sets up Node, gitleaks and lefthook at pinned versions. `lefthook install` adds the pre-commit hooks (secret scan, lint and types).
+
+| Command | What it does |
+|---|---|
+| `npm run format` | Format and auto-fix everything |
+| `npm run check` | Full gate: format check, lint, types, Svelte types, unused code, tests |
+| `npm run check:fast` | Lint and types only |
+
+Docs: `docs/PROJECT.md` (what and why), `docs/ARCHITECTURE.md` (how), `docs/PLAN.md` (build plan). Rules for people and coding agents: `AGENTS.md`.
+
+## Deploy
+
+Ask Miyagi ships as the npm package [`askmiyagi`](https://www.npmjs.com/package/askmiyagi). To release, bump `version` in `package.json` and run `npm publish`; `prepublishOnly` runs `npm run check`, which builds `dist`, first. At release, rename `[Unreleased]` in `CHANGELOG.md` to the version and date.
+
+## License
+
+Copyright (C) 2026 Sarthak Kumar.
+
+Ask Miyagi is free software under the [GNU Affero General Public License v3.0](LICENSE) (`AGPL-3.0-only`). You may use, study, change and share it. If you share a changed version, or let other people use a changed version over a network, you must make its full source available under the same licence. Code adapted or bundled from other projects is credited in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,62 @@
+# Third-party notices
+
+## claude-loopback
+
+`src/server/llm/claude-process.ts` and the Claude stream parser adapt spawn, argument, stream-parsing and process-tree kill code from claude-loopback (github.com/ssaarthakk/claude-loopback).
+
+```
+MIT License
+
+Copyright (c) 2026 Sarthak Kumar
+
+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.
+```
+
+## Browser app bundle
+
+`dist/web` bundles code from these MIT-licensed packages:
+
+- `svelte`: Copyright (c) 2016-2025 Svelte Contributors
+- `codemirror`, `@codemirror/view`, `@codemirror/state`, `@codemirror/language`, `@codemirror/lang-javascript`, `@codemirror/commands`, `@codemirror/search`, `@codemirror/autocomplete`, `@codemirror/lint`: Copyright (C) 2018-2021 by Marijn Haverbeke and others
+- `@lezer/common`, `@lezer/highlight`, `@lezer/lr`, `@lezer/javascript`, `style-mod`: Copyright (C) 2018 by Marijn Haverbeke and others
+- `w3c-keyname`: Copyright (C) 2016 by Marijn Haverbeke and others
+- `crelt`: Copyright (C) 2020 by Marijn Haverbeke
+- `@marijn/find-cluster-break`: Copyright (C) 2024 by Marijn Haverbeke
+
+Each is released under the MIT License:
+
+```
+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/dist/server/cli-args.js

@@ -0,0 +1,85 @@
+import { parseArgs } from "node:util";
+import { z } from "zod";
+const defaultVoiceId = "JBFqnCBsd6RMkjVDRZzb";
+const cliArgsSchema = z.object({
+    positionals: z.array(z.string()).max(1, "Only one project path or URL can be provided"),
+    port: z
+        .string()
+        .regex(/^\d+$/, "Port must be an integer between 0 and 65535")
+        .transform(Number)
+        .pipe(z.number().int().min(0).max(65535))
+        .optional(),
+    noOpen: z.boolean(),
+    provider: z
+        .enum(["fake"], { error: (issue) => `Unknown provider: ${String(issue.input)}` })
+        .optional(),
+    recording: z.string().min(1).optional(),
+    voice: z
+        .enum(["browser", "elevenlabs"], { error: (issue) => `Unknown voice: ${String(issue.input)}` })
+        .optional(),
+    voiceId: z.string().min(1, "--voice-id must not be empty").optional(),
+    model: z
+        .string()
+        .regex(/^\w[\w.-]*$/, "--model must be a model name such as sonnet")
+        .optional(),
+    bruteForceTokens: z
+        .string()
+        .regex(/^[1-9]\d*$/, "--brute-force-tokens must be a positive integer")
+        .transform(Number)
+        .optional(),
+});
+export function parseCliArgs(args) {
+    const parsed = parseArgs({
+        args,
+        options: {
+            port: { type: "string" },
+            "no-open": { type: "boolean" },
+            provider: { type: "string" },
+            recording: { type: "string" },
+            voice: { type: "string" },
+            "voice-id": { type: "string" },
+            "brute-force-tokens": { type: "string" },
+            model: { type: "string" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const validated = cliArgsSchema.safeParse({
+        positionals: parsed.positionals,
+        port: parsed.values.port,
+        noOpen: parsed.values["no-open"] ?? false,
+        provider: parsed.values.provider,
+        recording: parsed.values.recording,
+        voice: parsed.values.voice,
+        voiceId: parsed.values["voice-id"],
+        bruteForceTokens: parsed.values["brute-force-tokens"],
+        model: parsed.values.model,
+    });
+    if (!validated.success) {
+        throw new Error(validated.error.issues.map((issue) => issue.message).join("\n"));
+    }
+    const { provider, recording } = validated.data;
+    if (provider === "fake" && !recording) {
+        throw new Error("--provider fake needs --recording <file>");
+    }
+    if (recording && provider !== "fake") {
+        throw new Error("--recording only works with --provider fake");
+    }
+    return {
+        path: validated.data.positionals[0] ?? ".",
+        port: validated.data.port ?? 0,
+        noOpen: validated.data.noOpen,
+        provider,
+        recording,
+        voice: validated.data.voice ?? "browser",
+        voiceId: validated.data.voiceId ?? defaultVoiceId,
+        bruteForceTokens: validated.data.bruteForceTokens,
+        model: validated.data.model,
+    };
+}
+export function speechOptions(options, env) {
+    return {
+        apiKey: options.voice === "elevenlabs" ? env.ELEVENLABS_API_KEY : undefined,
+        voiceId: options.voiceId,
+    };
+}

package/dist/server/cli.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseCliArgs, speechOptions } from "./cli-args.js";
+import { createAskHandler } from "./http/ask-route.js";
+import { createFileHandler } from "./http/file-route.js";
+import { serveRequest } from "./http/serve.js";
+import { createSpeechHandler } from "./http/speech-route.js";
+import { createTranscribeHandler } from "./http/transcribe-route.js";
+import { claudeHeadless } from "./llm/claude-headless.js";
+import { loadFakeProvider } from "./llm/fake-provider.js";
+import { runMcpCommand } from "./mcp/server.js";
+import { openGitClone } from "./source/git-clone.js";
+import { openLocalFolder } from "./source/local-folder.js";
+import { projectName } from "./source/project-name.js";
+export function closeServer(server, source) {
+    return new Promise((resolveClose) => {
+        server.close(() => resolveClose());
+        server.closeAllConnections();
+    }).then(() => source.dispose());
+}
+function openBrowser(url) {
+    const [command, args] = process.platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+        : process.platform === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+    try {
+        const browser = spawn(command, args, { shell: false, detached: true, stdio: "ignore" });
+        let failed = false;
+        const reportFailure = () => {
+            if (failed)
+                return;
+            failed = true;
+            process.stderr.write(`Open ${url} in your browser\n`);
+        };
+        browser.once("error", reportFailure);
+        browser.once("exit", (code) => {
+            if (code !== 0)
+                reportFailure();
+        });
+        browser.unref();
+    }
+    catch {
+        process.stderr.write(`Open ${url} in your browser\n`);
+    }
+}
+async function runCli() {
+    const [subcommand, ...subcommandArgs] = process.argv.slice(2);
+    if (subcommand === "mcp") {
+        await runMcpCommand(subcommandArgs);
+        return;
+    }
+    let options;
+    try {
+        options = parseCliArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.voice === "elevenlabs" && !process.env.ELEVENLABS_API_KEY) {
+        process.stderr.write("Set ELEVENLABS_API_KEY to use --voice elevenlabs\n");
+        process.exitCode = 1;
+        return;
+    }
+    const interrupted = new AbortController();
+    process.on("SIGINT", () => interrupted.abort());
+    process.on("SIGTERM", () => interrupted.abort());
+    const source = /^[a-z][a-z0-9+.-]*:\/\//i.test(options.path)
+        ? await openGitClone(options.path, interrupted.signal)
+        : await openLocalFolder(options.path);
+    if (!source.ok) {
+        process.stderr.write(`${source.error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let provider = claudeHeadless(options.model);
+    if (options.provider === "fake" && options.recording) {
+        const fake = await loadFakeProvider(resolve(options.recording));
+        if (!fake.ok) {
+            process.stderr.write(`${fake.error}
+`);
+            await source.value.dispose();
+            process.exitCode = 1;
+            return;
+        }
+        provider = fake.value;
+    }
+    const handleAsk = createAskHandler({
+        root: source.value.root,
+        provider,
+        bruteForceTokens: options.bruteForceTokens,
+    });
+    const handleFile = createFileHandler(source.value.root);
+    const speech = speechOptions(options, process.env);
+    const handleSpeech = createSpeechHandler(speech);
+    const handleTranscribe = createTranscribeHandler({ apiKey: speech.apiKey });
+    const webRoot = resolve(import.meta.dirname, "../../dist/web");
+    let page;
+    const sessionToken = randomBytes(32).toString("hex");
+    try {
+        const template = await readFile(resolve(webRoot, "index.html"), "utf8");
+        page = template.replace("</head>", `<meta name="miyagi-token" content="${sessionToken}"><meta name="miyagi-voice" content="${options.voice}"><meta name="miyagi-project" content="${encodeURIComponent(projectName(options.path, source.value.root))}"></head>`);
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            process.stderr.write("Run npm run build first\n");
+        }
+        else {
+            process.stderr.write(`Could not read built page: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        await source.value.dispose();
+        process.exitCode = 1;
+        return;
+    }
+    let serverPort;
+    const server = createServer((request, response) => {
+        void serveRequest(request, response, webRoot, page, sessionToken, serverPort, handleAsk, handleFile, handleSpeech, handleTranscribe).catch((error) => {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            if (!response.headersSent)
+                response.writeHead(500);
+            response.end();
+        });
+    });
+    try {
+        await new Promise((resolveListen, rejectListen) => {
+            server.once("error", rejectListen);
+            server.listen(options.port, "127.0.0.1", resolveListen);
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Could not start server: ${error instanceof Error ? error.message : String(error)}\n`);
+        await source.value.dispose();
+        process.exitCode = 1;
+        return;
+    }
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        process.stderr.write("Could not determine server address\n");
+        await source.value.dispose();
+        server.close();
+        process.exitCode = 1;
+        return;
+    }
+    serverPort = address.port;
+    const url = `http://127.0.0.1:${address.port}/`;
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void closeServer(server, source.value).then(() => {
+            process.exitCode = 0;
+        }, (error) => {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        });
+    };
+    interrupted.signal.addEventListener("abort", shutdown, { once: true });
+    if (interrupted.signal.aborted)
+        shutdown();
+    process.stdout.write(`${url}\n`);
+    if (!options.noOpen)
+        openBrowser(url);
+}
+function startedAsCli() {
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1] ?? "")).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (startedAsCli()) {
+    void runCli();
+}

package/dist/server/code/anchor-resolver.js

@@ -0,0 +1,108 @@
+import { readRedactedFile } from "../files/path-guard.js";
+import { parseFile } from "./parse-cache.js";
+import { uniqueDefinition } from "./symbols.js";
+const maxBlockLines = 40;
+const statementOrDeclaration = /(_statement|_declaration|_definition|_signature)$/;
+function block(file, start, end, line = start) {
+    const shownStart = Math.max(start, line - maxBlockLines + 1);
+    return {
+        ok: true,
+        value: {
+            file,
+            start: shownStart,
+            end: Math.min(end, shownStart + maxBlockLines - 1),
+            capped: end - start + 1 > maxBlockLines,
+        },
+    };
+}
+function collapsed(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function nearestLine(lines, line, matches) {
+    let nearest;
+    lines.forEach((candidate, index) => {
+        const number = index + 1;
+        if (matches(candidate) &&
+            (nearest === undefined || Math.abs(number - line) < Math.abs(nearest - line))) {
+            nearest = number;
+        }
+    });
+    return nearest;
+}
+function nearestMatchingLine(lines, line, text) {
+    const wanted = collapsed(text);
+    return (nearestLine(lines, line, (candidate) => collapsed(candidate) === wanted) ??
+        (wanted.length >= 8
+            ? nearestLine(lines, line, (candidate) => collapsed(candidate).includes(wanted))
+            : undefined));
+}
+function declarationPatterns(name) {
+    const word = `(?<![\\w$])${name.replaceAll("$", "\\$")}(?![\\w$])`;
+    const modifiers = "(export\\s+|async\\s+|static\\s+|public\\s+|private\\s+|protected\\s+)*";
+    return [
+        new RegExp(`\\b(function|class|interface|type|enum|const|let|var|def|fn|func)\\s+${word}`),
+        new RegExp(`^\\s*${modifiers}${word}\\s*[(<].*(\\{|=>)\\s*$`),
+        new RegExp(`${word}\\s*[:=]\\s*(async\\s*)?(\\(|function\\b)`),
+        new RegExp(`^(?!\\s*import\\b).*${word}`),
+    ];
+}
+function declarationLine(lines, symbol) {
+    const names = symbol.split(".");
+    if (!names.every((name) => /^[\w$]+$/.test(name)))
+        return undefined;
+    let from = 0;
+    if (names.length > 1) {
+        const [owner] = declarationPatterns(names.at(-2) ?? "");
+        from = lines.findIndex((candidate) => owner?.test(candidate));
+        if (from === -1)
+            return undefined;
+    }
+    for (const pattern of declarationPatterns(names.at(-1) ?? "")) {
+        const index = lines.findIndex((candidate, at) => at >= from && pattern.test(candidate));
+        if (index !== -1)
+            return index + 1;
+    }
+    return undefined;
+}
+function enclosingStatement(tree, text, line) {
+    const row = line - 1;
+    let node = tree.rootNode.descendantForPosition({ row, column: text.length - text.trimStart().length }, { row, column: text.trimEnd().length });
+    while (node && !statementOrDeclaration.test(node.type))
+        node = node.parent;
+    return node;
+}
+export async function resolveAnchor(root, anchor) {
+    const file = await readRedactedFile(root, anchor.file);
+    if (!file.ok)
+        return file;
+    const { relPath, source } = file.value;
+    const tree = await parseFile(relPath, source);
+    if ("symbol" in anchor) {
+        const symbol = anchor.symbol.trim();
+        const found = tree ? uniqueDefinition(tree.rootNode, relPath, symbol) : undefined;
+        if (found?.ok) {
+            const { startPosition, endPosition } = found.value.node;
+            return block(relPath, startPosition.row + 1, endPosition.row + 1);
+        }
+        const lines = source.split("\n");
+        const line = declarationLine(lines, symbol);
+        if (line === undefined) {
+            return found ?? { ok: false, error: `Symbol not found in ${relPath}: ${symbol}` };
+        }
+        const statement = tree && enclosingStatement(tree, lines[line - 1] ?? "", line);
+        return statement
+            ? block(relPath, statement.startPosition.row + 1, statement.endPosition.row + 1, line)
+            : block(relPath, line, line);
+    }
+    const text = anchor.text.trim();
+    if (!text)
+        return { ok: false, error: "Anchor text is empty" };
+    const lines = source.split("\n");
+    const line = nearestMatchingLine(lines, anchor.line, text);
+    if (line === undefined)
+        return { ok: false, error: `Text not found in ${relPath}: ${text}` };
+    const statement = tree && enclosingStatement(tree, lines[line - 1] ?? "", line);
+    return statement
+        ? block(relPath, statement.startPosition.row + 1, statement.endPosition.row + 1, line)
+        : block(relPath, line, line);
+}

package/dist/server/code/parse-cache.js

@@ -0,0 +1,69 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { extname } from "node:path";
+import { Language, Parser } from "web-tree-sitter";
+const require = createRequire(import.meta.url);
+const grammarPaths = {
+    typescript: require.resolve("tree-sitter-typescript/tree-sitter-typescript.wasm"),
+    tsx: require.resolve("tree-sitter-typescript/tree-sitter-tsx.wasm"),
+    javascript: require.resolve("tree-sitter-javascript/tree-sitter-javascript.wasm"),
+};
+const treeCache = new Map();
+const languageCache = new Map();
+let parserInitialization;
+export const grammarsByExtension = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+};
+function grammarFor(path) {
+    return grammarsByExtension[extname(path)] ?? null;
+}
+export function hasParser(path) {
+    return grammarFor(path) !== null;
+}
+async function loadLanguage(grammar) {
+    let language = languageCache.get(grammar);
+    if (!language) {
+        language = Language.load(grammarPaths[grammar]);
+        languageCache.set(grammar, language);
+    }
+    return language;
+}
+async function parse(source, grammar) {
+    parserInitialization ??= Parser.init();
+    await parserInitialization;
+    const parser = new Parser();
+    try {
+        parser.setLanguage(await loadLanguage(grammar));
+        const tree = parser.parse(source);
+        if (tree === null)
+            throw new Error("Tree-sitter returned no parse tree");
+        return tree;
+    }
+    finally {
+        parser.delete();
+    }
+}
+export async function parseFile(path, source) {
+    const grammar = grammarFor(path);
+    if (grammar === null)
+        return null;
+    const hash = createHash("sha256").update(source).digest("hex");
+    const key = `${grammar}:${hash}`;
+    const cachedTree = treeCache.get(key);
+    if (cachedTree)
+        return cachedTree;
+    const pendingTree = parse(source, grammar).catch((error) => {
+        if (treeCache.get(key) === pendingTree)
+            treeCache.delete(key);
+        throw error;
+    });
+    treeCache.set(key, pendingTree);
+    return pendingTree;
+}