@illuminis/comprism 0.1.0

package/out/thin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/out/thin.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * The published command line tool.
+ *
+ * ── Why there are two entry points ────────────────────────────────────────
+ *
+ * `cli.ts` is the full internal tool. It reaches into the decision, the price
+ * list and the study, because our own work needs to. It is never published.
+ *
+ * THIS is what a customer installs. It carries no decision, no price list, no
+ * task representation and no study. Every question that needs any of those is
+ * asked of our server and only the answer comes back.
+ *
+ * The split is deliberate rather than tidy. A single entry point with the
+ * dangerous parts behind lazy imports still SHIPS them, and a package on a
+ * public registry is readable by anyone who installs it, forever. The only
+ * reliable way to not ship something is to not put it in the file that ships.
+ *
+ * The rule, from the owner: anything a client installs is thin; anything
+ * model-related runs on our server.
+ */
+const ui = __importStar(require("./lib/ui"));
+const version_1 = require("./lib/version");
+const out = (s = '') => process.stdout.write(s + '\n');
+/**
+ * The value after a flag, or undefined when the flag was not given.
+ *
+ * `args[args.indexOf('--mode') + 1]` reads the FIRST argument when the flag is
+ * absent, because `indexOf` answers -1 and -1 + 1 is 0. So
+ * `comprism work "create a.txt"` took the request itself as the permission mode
+ * and refused the whole command before it started: the plainest way anybody
+ * runs this tool was the one way it could not be run.
+ */
+function flag(args, name) {
+    const at = args.indexOf(name);
+    return at === -1 ? undefined : args[at + 1];
+}
+function usage() {
+    out(ui.banner('CompletionPrism'));
+    out(ui.c.dim('  Every answer on the model that finishes it for least, with a receipt.'));
+    out();
+    out(ui.table(['COMMAND', 'WHAT IT DOES'], [
+        ['comprism ask "<your question>"', 'one prompt, one answer, and what it cost'],
+        ['comprism work', 'have it do the work: reads your project, edits, runs your tests'],
+        ['comprism login', 'sign in with your email and password'],
+        ['comprism', 'start a session and just type your questions'],
+        ['comprism keys', 'add a provider key, or point at a file of them'],
+        ['comprism model', 'the model your savings are measured against'],
+        ['comprism providers', 'every AI vendor and model, and what you can reach'],
+        ['comprism workspace', 'the folder to work in, default is where you are'],
+        ['comprism status', 'is this machine signed in, and to what'],
+        ['comprism check', 'what this machine still needs, and how to add it'],
+        ['comprism logout', 'sign out, and revoke this machine\'s key'],
+    ]));
+    out();
+    out(ui.c.dim(`  v${version_1.COMPRISM_VERSION} · every decision is made on our servers`));
+    out();
+}
+async function main() {
+    const [, , command, ...args] = process.argv;
+    switch (command) {
+        case 'ask': {
+            const { cmdAsk } = await Promise.resolve().then(() => __importStar(require('./commands/ask')));
+            return cmdAsk(args);
+        }
+        // `work` is the word. `agent` still answers to it, because anybody who
+        // learned the old name should not meet "unknown command".
+        case 'work':
+        case 'agent': {
+            const { runAgent, AGENT_HELP } = await Promise.resolve().then(() => __importStar(require('./agent/command')));
+            if (args.includes('--help') || args.includes('-h')) {
+                out(AGENT_HELP);
+                return;
+            }
+            const { subject, closePrompt } = await Promise.resolve().then(() => __importStar(require('./lib/prompt')));
+            // Asked for when it was not given, same as every other command.
+            const request = await subject(args, '  what would you like done? ', ['--mode', '--model', '--max-spend', '--resume', '--cwd', '--allow']);
+            closePrompt();
+            if (!request) {
+                out(ui.fail('Nothing was asked for.'));
+                out();
+                return;
+            }
+            const spend = flag(args, '--max-spend');
+            process.exitCode = await runAgent({
+                request: [request],
+                mode: flag(args, '--mode'),
+                plan: args.includes('--plan'),
+                approvePlan: args.includes('--approve-plan'),
+                model: flag(args, '--model'),
+                pin: args.includes('--pin'),
+                ...(args.includes('--max-spend') ? { maxSpend: Number(spend) } : {}),
+                allow: args.reduce((acc, a, i) => (args[i - 1] === '--allow' ? [...acc, a] : acc), []),
+                yes: args.includes('--yes'),
+                background: args.includes('--background'),
+                resume: flag(args, '--resume'),
+                // Go without the code map for this one job. Two reasons somebody uses
+                // it: they are measuring, and a run with a map and a run without one
+                // are two different quantities; or they suspect the map and want the
+                // files read directly. Both are legitimate and neither should require
+                // an administrator.
+                noMap: args.includes('--no-map') || args.includes('--no-graph'),
+                // The saved working folder when there is one, so `comprism workspace`
+                // is a setting the agent honors rather than a stored string nothing reads.
+                cwd: flag(args, '--cwd')
+                    ?? (await Promise.resolve().then(() => __importStar(require('./commands/settings')))).currentWorkspace().path,
+            });
+            return;
+        }
+        // The map of the project you are standing in: what it holds, and a way to
+        // have it read again. `graph` answers to it as well, because that is what
+        // the thing is called in the documentation and in the patent.
+        case 'map':
+        case 'graph': {
+            const { cmdMap } = await Promise.resolve().then(() => __importStar(require('./commands/codemap')));
+            process.exitCode = await cmdMap(args);
+            return;
+        }
+        case 'login': {
+            const { cmdLogin } = await Promise.resolve().then(() => __importStar(require('./commands/login')));
+            await cmdLogin(args);
+            // Signing in is not the thing somebody came to do. It used to print the
+            // header and exit, so a person who had just signed in had to type the
+            // program's name a second time to get to a prompt. If the sign in
+            // worked and there is somebody at the keyboard, carry straight on into
+            // the session.
+            //
+            // Only with a terminal attached: a script that signs in must not be
+            // handed an interactive prompt and left waiting for a line that never
+            // comes. And only when it actually worked, which the exit code says.
+            if (!process.exitCode && process.stdin.isTTY) {
+                const { runRepl } = await Promise.resolve().then(() => __importStar(require('./commands/repl')));
+                return runRepl();
+            }
+            return;
+        }
+        // Kept as a second name for the same job. Anybody who learned the old word
+        // should not hit "unknown command" for it.
+        case 'connect': {
+            const { cmdLogin } = await Promise.resolve().then(() => __importStar(require('./commands/login')));
+            return cmdLogin(args);
+        }
+        // The three words people type for the same act. `logout` used to answer
+        // "there is no command called logout", which is the product telling
+        // somebody their own vocabulary is wrong.
+        case 'logout':
+        case 'signout':
+        case 'disconnect': {
+            const { cmdDisconnect } = await Promise.resolve().then(() => __importStar(require('./commands/commands-thin')));
+            return cmdDisconnect();
+        }
+        case 'model': {
+            const { cmdModel } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
+            return cmdModel(args);
+        }
+        case 'providers': {
+            const { cmdProviders } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
+            return cmdProviders();
+        }
+        case 'workspace': {
+            const { cmdWorkspace } = await Promise.resolve().then(() => __importStar(require('./commands/settings')));
+            return cmdWorkspace(args);
+        }
+        case 'keys': {
+            const { cmdKeys } = await Promise.resolve().then(() => __importStar(require('./commands/keys')));
+            return cmdKeys(args);
+        }
+        case 'status': {
+            const { cmdStatus } = await Promise.resolve().then(() => __importStar(require('./commands/commands-thin')));
+            return cmdStatus();
+        }
+        // What this machine still needs. Its own word because somebody whose PDF
+        // would not read has a question about THIS machine, and the answer should
+        // not be buried inside a setup command they have already run.
+        case 'check':
+        case 'doctor': {
+            const { check } = await Promise.resolve().then(() => __importStar(require('./lib/readiness')));
+            const machine = check();
+            out();
+            out(ui.banner('This machine'));
+            out();
+            for (const line of machine.lines)
+                out(line);
+            out();
+            if (machine.ready) {
+                out(ui.ok('Everything the work needs is here.'));
+            }
+            else {
+                out(`  ${ui.c.dim('to add what is missing:')} ${ui.c.bold(machine.fix)}`);
+            }
+            out();
+            out(ui.c.dim('  Word, PowerPoint and PDF documents are built on our servers,'));
+            out(ui.c.dim('  so nothing has to be installed here for those.'));
+            out();
+            return;
+        }
+        case '--version':
+        case '-v':
+            out(version_1.COMPRISM_VERSION);
+            return;
+        case 'help':
+        case '--help':
+        case '-h':
+            return usage();
+        default: {
+            // The bare command shows WHERE YOU ARE, not a list of other commands. A
+            // person who does not know which model their savings are measured
+            // against cannot read a saving, and they will not run three commands to
+            // find out. The command list is one word away, under `help`.
+            if (command) {
+                out(ui.fail(`There is no command called "${command}".`));
+                out();
+                return usage();
+            }
+            // The bare command STARTS the product rather than describing it.
+            const { runRepl } = await Promise.resolve().then(() => __importStar(require('./commands/repl')));
+            return runRepl();
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(ui.fail(err instanceof Error ? err.message : 'something went wrong') + '\n');
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@illuminis/comprism",
+  "version": "0.1.0",
+  "description": "CompletionPrism Companion. Records what finishing a piece of work actually costs - every attempt, and the human time spent noticing and repairing the ones that failed.",
+  "license": "UNLICENSED",
+  "private": false,
+  "main": "out/thin.js",
+  "types": "out/thin.d.ts",
+  "bin": {
+    "comprism": "out/thin.js"
+  },
+  "files": [
+    "out/thin.js",
+    "out/thin.d.ts",
+    "out/postinstall.js",
+    "out/postinstall.d.ts",
+    "out/commands/install.js",
+    "out/commands/install.d.ts",
+    "out/lib/config.js",
+    "out/lib/config.d.ts",
+    "out/lib/connection.js",
+    "out/lib/connection.d.ts",
+    "out/lib/gateway.js",
+    "out/lib/gateway.d.ts",
+    "out/lib/prompt.js",
+    "out/lib/prompt.d.ts",
+    "out/lib/types.js",
+    "out/lib/types.d.ts",
+    "out/lib/ui.js",
+    "out/lib/ui.d.ts",
+    "out/lib/version.js",
+    "out/lib/version.d.ts",
+    "out/lib/attach.js",
+    "out/lib/attach.d.ts",
+    "out/lib/voice.js",
+    "out/lib/voice.d.ts",
+    "out/commands/ask.js",
+    "out/commands/ask.d.ts",
+    "out/commands/commands-thin.js",
+    "out/commands/commands-thin.d.ts",
+    "out/commands/keys.js",
+    "out/commands/keys.d.ts",
+    "out/commands/login.js",
+    "out/commands/login.d.ts",
+    "out/commands/repl.js",
+    "out/commands/repl.d.ts",
+    "out/commands/settings.js",
+    "out/commands/settings.d.ts",
+    "out/commands/welcome.js",
+    "out/commands/welcome.d.ts",
+    "out/graph/**",
+    "out/commands/codemap.js",
+    "out/commands/codemap.d.ts",
+    "scripts/read_python.py",
+    "out/agent/**",
+    "out/executor/**",
+    "!out/internal/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p ./",
+    "dev": "tsc -w -p ./",
+    "test": "npm run build && node --test out/**/*.test.js",
+    "gate": "npm run build && npm test && npm run shipcheck",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
+    "postinstall": "node out/postinstall.js || true",
+    "shipcheck": "node scripts/check-no-model-logic.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Illuminis-ai/completionprism.git",
+    "directory": "app/cli"
+  },
+  "keywords": [
+    "ai",
+    "cost",
+    "observability",
+    "llm",
+    "completion"
+  ],
+  "author": "illuminis.ai LLC",
+  "homepage": "https://completionprism.illuminis.ai",
+  "bugs": {
+    "url": "https://github.com/Illuminis-ai/completionprism/issues"
+  },
+  "dependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/scripts/read_python.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Read Python files into code map facts, using Python's own parser.
+
+This is a parser, not a model. Nothing here guesses: every object and every
+link comes from the syntax tree, so the same file always produces the same
+facts and two machines reading one project agree.
+
+It runs on the person's own machine and prints facts, never source. What
+leaves is "a function called price_of exists at line 40 of this file, and
+these things call it". What it says is never read by anything but the parser.
+
+Usage:  read_python.py <project-root> <relative-path-list-file>
+Writes one JSON object to stdout.
+"""
+import ast
+import json
+import os
+import sys
+
+ROUTE_METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
+MODEL_BASE_HINTS = {"Base", "BaseDataMixin", "DeclarativeBase", "Model",
+                    "SQLModel", "models.Model"}
+COLUMN_FACTORIES = {"Column", "mapped_column", "relationship"}
+
+
+def dotted(node):
+    """Render a Name / Attribute chain back to its source text."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = dotted(node.value)
+        return "%s.%s" % (base, node.attr) if base else node.attr
+    if isinstance(node, ast.Call):
+        return dotted(node.func)
+    if isinstance(node, ast.Subscript):
+        return dotted(node.value)
+    return ""
+
+
+def literal_str(node):
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+class ModuleReader(ast.NodeVisitor):
+    def __init__(self, file_id, module_path):
+        self.file_id = file_id
+        self.module_path = module_path
+        self.objects = []
+        self.links = []
+        self.scope = []
+        self.owner = [file_id]
+        self.router_prefixes = {}
+        self.mounts = []
+
+    def qual(self, name):
+        return ".".join(self.scope + [name])
+
+    def add_object(self, object_id, kind, name, line, **extra):
+        entry = {"id": object_id, "kind": kind, "name": name,
+                 "file": self.file_id, "line": line}
+        entry.update({k: v for k, v in extra.items() if v not in (None, [], "")})
+        self.objects.append(entry)
+
+    def add_link(self, src, kind, dst=None, to_name=None, **extra):
+        link = {"from": src, "kind": kind}
+        if dst:
+            link["to"] = dst
+        if to_name:
+            link["to_name"] = to_name
+        link.update(extra)
+        self.links.append(link)
+
+    # ---- imports ---------------------------------------------------------
+    def visit_Import(self, node):
+        for alias in node.names:
+            self.add_link(self.file_id, "imports", to_name=alias.name, line=node.lineno)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node):
+        module = node.module or ""
+        if node.level:
+            base = self.module_path.rsplit(".", node.level)[0]
+            module = "%s.%s" % (base, module) if module else base
+        for alias in node.names:
+            self.add_link(
+                self.file_id, "imports",
+                to_name=("%s.%s" % (module, alias.name)) if module else alias.name,
+                line=node.lineno)
+        self.generic_visit(node)
+
+    # ---- routers ---------------------------------------------------------
+    def visit_Assign(self, node):
+        """`router = APIRouter(prefix="/billing")` fixes every path below it."""
+        if not self.scope and isinstance(node.value, ast.Call):
+            leaf = dotted(node.value.func).split(".")[-1]
+            if leaf in ("APIRouter", "Blueprint", "Router"):
+                prefix = ""
+                for kw in node.value.keywords:
+                    if kw.arg in ("prefix", "url_prefix"):
+                        prefix = literal_str(kw.value) or ""
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        self.router_prefixes[target.id] = prefix
+        self.generic_visit(node)
+
+    def _include_router(self, node):
+        """`include_router(billing.router, prefix="/api")` mounts a whole file."""
+        prefix = ""
+        for kw in node.keywords:
+            if kw.arg in ("prefix", "url_prefix"):
+                prefix = literal_str(kw.value) or ""
+        if not node.args:
+            return
+        target = dotted(node.args[0])
+        if target:
+            self.mounts.append({"target": target, "prefix": prefix, "line": node.lineno})
+
+    # ---- classes ---------------------------------------------------------
+    def visit_ClassDef(self, node):
+        qual = self.qual(node.name)
+        object_id = "%s::%s" % (self.file_id, qual)
+        bases = [dotted(b) for b in node.bases]
+        tablename = None
+        columns = []
+        for stmt in node.body:
+            if isinstance(stmt, ast.Assign):
+                for target in stmt.targets:
+                    if isinstance(target, ast.Name):
+                        if target.id == "__tablename__":
+                            tablename = literal_str(stmt.value)
+                        elif isinstance(stmt.value, ast.Call) and \
+                                dotted(stmt.value.func).split(".")[-1] in COLUMN_FACTORIES:
+                            columns.append(target.id)
+            elif isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                if isinstance(stmt.value, ast.Call) and \
+                        dotted(stmt.value.func).split(".")[-1] in COLUMN_FACTORIES:
+                    columns.append(stmt.target.id)
+
+        is_model = bool(tablename) or any(
+            b.split(".")[-1] in MODEL_BASE_HINTS for b in bases)
+        self.add_object(object_id, "model" if is_model else "class", qual,
+                        node.lineno, bases=bases, table=tablename, columns=columns)
+        self.add_link(self.file_id, "defines", object_id)
+        for base in bases:
+            self.add_link(object_id, "inherits", to_name=base)
+        if tablename:
+            table_id = "table:%s" % tablename
+            self.add_object(table_id, "table", tablename, node.lineno)
+            self.add_link(object_id, "maps_to", table_id)
+
+        self.scope.append(node.name)
+        self.owner.append(object_id)
+        self.generic_visit(node)
+        self.owner.pop()
+        self.scope.pop()
+
+    # ---- functions -------------------------------------------------------
+    def _function(self, node, is_async):
+        qual = self.qual(node.name)
+        object_id = "%s::%s" % (self.file_id, qual)
+        decorators = [dotted(d) for d in node.decorator_list]
+        self.add_object(object_id, "method" if self.scope else "function", qual,
+                        node.lineno, decorators=decorators,
+                        is_async=is_async or None,
+                        args=[a.arg for a in node.args.args])
+        self.add_link(self.file_id, "defines", object_id)
+
+        # An endpoint: @router.get("/things"). The path here is RELATIVE to its
+        # own router; the service puts the two halves back together.
+        for dec in node.decorator_list:
+            if not isinstance(dec, ast.Call):
+                continue
+            target = dotted(dec.func)
+            verb = target.split(".")[-1].lower()
+            if verb not in ROUTE_METHODS:
+                continue
+            path = literal_str(dec.args[0]) if dec.args else None
+            if path is None:
+                continue
+            router_var = target.rsplit(".", 1)[0] if "." in target else ""
+            route_id = "route:%s %s@%s" % (verb.upper(), path, self.file_id)
+            self.add_object(route_id, "route", "%s %s" % (verb.upper(), path),
+                            node.lineno, method=verb.upper(), path=path,
+                            router_var=router_var)
+            self.add_link(route_id, "handled_by", object_id)
+            self.add_link(self.file_id, "declares", route_id)
+
+        self.scope.append(node.name)
+        self.owner.append(object_id)
+        self.generic_visit(node)
+        self.owner.pop()
+        self.scope.pop()
+
+    def visit_FunctionDef(self, node):
+        self._function(node, False)
+
+    def visit_AsyncFunctionDef(self, node):
+        self._function(node, True)
+
+    def visit_Name(self, node):
+        """A capitalized name used in an expression is nearly always a class or
+        a model being referenced, which is how database usage shows up."""
+        if isinstance(node.ctx, ast.Load) and node.id[:1].isupper():
+            self.add_link(self.owner[-1], "references", to_name=node.id, line=node.lineno)
+        self.generic_visit(node)
+
+    def visit_Call(self, node):
+        target = dotted(node.func)
+        if target.split(".")[-1] in ("include_router", "register_blueprint"):
+            self._include_router(node)
+        if target:
+            leaf = target.split(".")[-1]
+            if leaf and not leaf.startswith("_"):
+                self.add_link(self.owner[-1], "calls", to_name=leaf,
+                              full_name=target, line=node.lineno)
+        self.generic_visit(node)
+
+
+def module_path_for(rel_path):
+    trimmed = rel_path[:-3]
+    if trimmed.endswith("/__init__"):
+        trimmed = trimmed[: -len("/__init__")]
+    return trimmed.replace("/", ".")
+
+
+def main():
+    if len(sys.argv) < 3:
+        sys.stderr.write("usage: read_python.py <project-root> <path-list-file>\n")
+        return 2
+    root = os.path.abspath(sys.argv[1])
+    with open(sys.argv[2], "r", encoding="utf8") as handle:
+        rels = [line.strip() for line in handle if line.strip()]
+
+    facts = {}
+    failures = []
+    for rel_path in rels:
+        full = os.path.join(root, rel_path)
+        try:
+            with open(full, "r", encoding="utf-8") as handle:
+                source = handle.read()
+            tree = ast.parse(source, filename=rel_path)
+        except (SyntaxError, UnicodeDecodeError, OSError, ValueError) as exc:
+            failures.append({"file": rel_path, "reason": type(exc).__name__})
+            continue
+
+        reader = ModuleReader(rel_path, module_path_for(rel_path))
+        reader.visit(tree)
+        entry = {
+            "objects": [{
+                "id": rel_path, "kind": "file",
+                "name": os.path.basename(rel_path), "file": rel_path, "line": 1,
+                "lang": "python", "lines": source.count("\n") + 1,
+                "module": module_path_for(rel_path),
+            }] + reader.objects,
+            "links": reader.links,
+        }
+        if reader.router_prefixes or reader.mounts:
+            entry["routers"] = {"prefixes": reader.router_prefixes,
+                                "mounts": reader.mounts}
+        facts[rel_path] = entry
+
+    json.dump({"facts": facts, "failures": failures}, sys.stdout,
+              separators=(",", ":"))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())