MEOW RUNTIME AND TOOLCHAIN SPECIFICATION (LLMS.TXT)

INDEX

1.  SYSTEM OVERVIEW & CORE PHILOSOPHY
2.  INSTALLATION & DIRECTORY STRUCTURE
3.  CONFIGURATION SPECIFICATION (meow.config.json & package.json)
4.  RUNTIME MODES & DETERMINISM MECHANICS
5.  THE PACKAGE MANAGER (Commands, Cache, Materialization, Lockfile)
6.  THE EXECUTION LAYER (Runners, Shims, Workers, Permissions)
7.  MODULE RESOLUTION & INTEROP
8.  BUILT-IN MODULES (meow:http, meow:ui, meow:test)
9.  TYPESCRIPT COMPILATION PIPELINE
10. STATIC ANALYSIS & TOOLING (Check, Lint, Fmt, Bundle)
11. OBSERVABILITY DIAGNOSTICS
12. CLI COMPLETE COMMAND & FLAG REFERENCE

1. SYSTEM OVERVIEW & CORE PHILOSOPHY

meow is a single-binary JavaScript/TypeScript runtime, package manager, and
development toolchain built in Rust.

  - Engine: Built on a tuned V8 build embedded via deno_core.
  - AST Shared Model: Uses a single lossless parse via Oxc [9] to drive the
    formatter, linter, type-stripping runtime, and bundler [12]. No redundant
    parsing passes [12].
  - Execution: Multi-isolate cooperative single-threaded scheduling on a Tokio
    LocalSet [12]. Offloads file writing, SHA-512 verification, and tarball
    decompression to background OS threads to preserve event loop latency [12].
  - Design Tension: "Floof" (terminal UX, Bento-panels, diagnostic frames)
    paired with "Teeth" (zero-copy, copy-on-write, fat-LTO Rust engineering)
    [12].

2. INSTALLATION & DIRECTORY STRUCTURE

Installer

curl -fsSL https://meow.style/install | sh [15] drops the binary into
~/.meow/bin and updates the environment PATH [15].

Global State Directory (~/.meow / relocatable via MEOW_HOME [11])

  - ~/.meow/bin: Main executable and the node/npm/npx/bun/yarn shims [15].
  - ~/.meow/cache/<algo>/<hash>: Content-addressed store for package tarball
    blobs [3, 15].
  - ~/.meow/cache/metadata: Unpacked npm registry metadata with a 5-minute
    freshness cache [3, 15].
  - ~/.meow/cache/unpacked: Extracted store of package files [15].
  - ~/.meow/global: Globally installed package links via meow add -g [4, 15].

Project Directory Structure

project/
├── meow.config.json      # Workspace, lint, and runtime configuration (User Edited)
├── package.json          # Dependency authority, metadata, scripts (User/CLI Edited)
├── meow.lock.jsonl       # Resolved deterministic dependency graph (Auto-Generated, Commit)
├── tsconfig.json         # Editor shim referencing .meow/tsconfig.json (Auto-Generated, Commit)
├── .meow/                # Internal compiler artifact cache (Gitignored)
│   ├── tsconfig.json     # Absolute compiler settings for LSP / tsc
│   ├── strict-web.d.ts   # Ambient global declarations for strict-web mode
│   └── types/meow/       # Types for first-party meow:* modules
└── node_modules/         # Materialized runtime dependency targets (Gitignored)
    └── .meow/            # Copy-on-write store and flat layout edges

3. CONFIGURATION SPECIFICATION

meow.config.json

A closed-schema, camelCase JSON file [1]. Unknown keys raise parsing errors [1].
Typing meow.config.ts yields a descriptive meow.config.ts evaluation is not yet
supported error without executing [1].

{
  "mode": "strict-web", // "strict-web" | "node-compat" | "legacy" (Active)
  "workspace": {
    "packages": ["apps/*", "packages/*"] // Glob roots for monorepo (Accepted)
  },
  "runtime": {
    "typescript": "strip" // Type handling strategy. Only "strip" is supported (Active)
  },
  "install": {
    "mode": "pnp" // "pnp" | "vfs" | "materialized" | "vendor" (Accepted)
  },
  "lint": {
    "rules": {
      "no-debugger": "error" // Rule mappings to "off" | "warn" | "error" (Active)
    }
  },
  "format": {
    "style": "meow" // Formatting rules style. Only "meow" supported (Active)
  },
  "types": {
    "strict": true // Directly maps to tsconfig.json "strict" parameter (Active)
  },
  "test": {
    "isolate": true, // Run test suites in distinct hermetic V8 isolates (Accepted)
    "clock": "deterministic", // "deterministic" | "system" (Accepted)
    "network": "fake" // "fake" | "real" (Accepted)
  },
  "permissions": {
    "default": [], // Capability grant defaults (Accepted/Reserved)
    "packages": {} // Map of package names to capability strings (Accepted/Reserved)
  }
}

package.json

Authority for metadata, script definitions, and dependencies [2]. meow only
modifies dependency objects during direct CLI mutating commands (add, remove,
install) [2].

  - Duplicate Specifiers: Declaring the same package across dependencies and
    devDependencies with divergent version specifiers causes meow to reject
    resolution with an error [2].
  - Compatibility Lockfile: Executing meow install --compat-lockfile writes a
    minimal placeholder package-lock.json containing
    "meowCompatibilityLockfile": true to appease external framework detectors,
    keeping meow.lock.jsonl as the source of truth [2, 12].

4. RUNTIME MODES & DETERMINISM MECHANICS

| Capability / Behavior | `strict-web` Mode                                                           | `node-compat` Mode                                                        |
| :-------------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| **Web Globals**       | Fetch, URL, URLPattern, Encoding, SubtleCrypto, AbortController \[8, 13\]   | Fetch, URL, URLPattern, Encoding, SubtleCrypto, AbortController \[8, 13\] |
| **Node.js Surface**   | Withdrawn. Imports trigger `ERR_STRICT_WEB_WITHDRAWN` at execution \[14\]   | `node:*` built-ins, CommonJS `require()`, N-API native addons \[12\]      |
| **Host Environment**  | Sandbox. `process` is absent; env hidden unless granted \[11, 14\]          | Full host `process.env` exposed automatically \[11, 14\]                  |
| **Wall Clock**        | Frozen virtual origin: `2026-06-07T00:00:00Z` (Unix `1780790400000`) \[21\] | Evaluates real system host clock \[21\]                                   |
| **Time Progression**  | Moves only when asynchronous timer queues (`setTimeout`) dispatch \[21\]    | Native real-time wall-clock progression \[21\]                            |
| **Randomness**        | ChaCha20 CSPRNG driven by a fixed, stable 32-byte seed \[21\]               | Native OS entropy \[21\]                                                  |
| **Locale / Timezone** | Pinned to `TZ=UTC` and `en_US.UTF-8` on Isolate instantiation \[21\]        | System host locale and host timezone settings \[21\]                      |

Note: meow test isolates always enforce strict-web deterministic defaults
regardless of the global project mode configuration [14, 21].

5. THE PACKAGE MANAGER

Core CLI Commands

  - meow install (alias i): Resolves dependency graph, writes lockfile,
    materializes node_modules [3, 17].
  - meow add <package>: Appends dependency to package.json (unversioned defaults
    to latest tag) and triggers install [3, 17]. Use -D or --dev for
    devDependencies, -g or --global for global installation [17].
  - meow remove <package> (aliases rm, del, delete, uninstall): Removes entry
    from package.json and runs install [3, 17].

Optimization Architecture

  - Mathematical Resolve: Tarball URLs are mathematically constructed from
    package name and version [3]. Does not trust arbitrary URLs returned by
    registry endpoints to prevent cache-poisoning [3].
  - Concurrent Pipelines: High metadata fan-out and up to 40 concurrent tarball
    downloads with exponential-backoff retries for status codes 429 and 5xx [3].
  - EMFILE Semaphore: High-concurrency filesystem writes pass through an
    internal semaphore to prevent exceeding OS open file descriptors limits [3].
  - Self-Healing Cache: Every read from ~/.meow/cache re-computes and asserts
    SHA-512 Subresource-Integrity [3]. Atomic writes (temp file write followed
    by rename) guarantee crash-safety [3].

node_modules Materialization Layout

Packages populate node_modules/.meow/<name>@<version>/node_modules/<name>/ [5].
Imports resolve to top-level names pointing into this path to construct a
deduplicated flat dependency graph [5].

  - macOS (APFS): Clones package files using clonefile for O(1) copy-on-write
    [5]. Edges materialized via symlinks [5].
  - Linux: Clones via recursive hardlinks [5]. Edges materialized via symlinks
    [5].
  - Windows: Clones via recursive hardlinks [5]. Edges materialized via NTFS
    directory junctions [5].
  - State Tracking: Sidecar file .materialized logs tree state [5]. If identical
    to current lockfile, materialization is bypassed [5].
  - Vendor Mode: meow install --vendor copies actual package contents into
    ./vendor/ (or custom --vendor-dir), normalizing mtimes for absolute binary
    reproducibility [5, 17].

The Lockfile (meow.lock.jsonl)

A JSON-Lines serialized document. Lines are strictly ordered lexicographically
by (name, version) to prevent git merge conflicts [6].

  - Canonical Form: Read checks are strictly canonical [6]. The parser rejects
    any lockfile that contains blank lines, non-canonical formatting
    (spaces/indent differences, modified key orders), duplicate records, or
    unsorted items [6].
  - JSON-Line Properties (Fixed Order Keys):
    {"name":"is-odd","version":"3.0.1","integrity":"sha512-...","dependencies":{"is-number":"6.0.0"},"registry":{"registry":"https://registry.npmjs.org"},"meow":"^0.1"}

6. THE EXECUTION LAYER

The Omni-Router

CLI command parser matching unknown subcommands against rules to map parameters
without throwing syntax exceptions [10]:

  - Matches script names defined in package.json -> routes to meow run <script>
    [10].
  - Matches absolute/relative file path on disk -> routes to meow run
    <file-path> [10].
  - Unmatched commands -> routes ephemerally to meow x <pkg> [10].
  - Cleans competitor-specific execution parameters (--shell, --silent,
    --no-warnings) [10].
  - Ignores Deno-style run configuration flags (-A, --allow-all, --unstable,
    --unstable-*) [10].

Script Engine Execution Pipeline

1.  Direct Fast-Path: If a script evaluates to a local JS/TS path or a
    dependency binary (e.g., node ./file.js, tsc, vite), meow executes it
    directly in the running process without spawning an shell [10].
2.  Shell Fallback: If script strings contain complex shell operators (&&,
    pipes, redirections, subshells, glob expressions), execution is delegated to
    sh -c (POSIX) or cmd /C (Windows) [10].
3.  Pre/Post script hooks execute automatically NPM-style; non-zero exit in pre
    aborts execution [10].

Ephemeral Execution (meow x / npx / bunx / pnpx / meowx)

Installs requested package into a localized transient workspace, executes the
referenced binary target, and cleanses the transient workspace on system exit
[4].

  - Security Context Warning: Displays isolation warnings unless bypassed using
    environment variable MEOW_DANGEROUSLY_DISABLE_SECURITY=1 or trailing --trust
    arguments [4, 11].

Workers (node:worker_threads)

Supported in node-compat mode [12]. Uses distinct V8 Isolates scheduled
cooperatively as tasks inside the main thread's Tokio LocalSet executor [12].

  - Sharing Model: Share zero memory [12]. Data transfer through standard
    postMessage passes via structured-clone serialization [12].
  - Supported surface: new Worker(), parentPort, workerData, .terminate(), error
    bubble propagation [12]. Nested workers are inert [12].

Environment Variables Matrix

| Environmental Key                   | Direction | Functionality                                                                             |
| :---------------------------------- | :-------- | :---------------------------------------------------------------------------------------- |
| `MEOW_HOME`                         | Read      | Relocates default global `~/.meow` directory \[11\].                                      |
| `MEOW_DANGEROUSLY_DISABLE_SECURITY` | Read      | `=1` grants absolute `--trust` host access on all invocations \[11, 20\].                 |
| `MEOW_NO_SHIM`                      | Read      | `=1` bypasses execution interception; routes straight to real system binaries \[11, 12\]. |
| `MEOW_METADATA_MAX_AGE_SECS`        | Read      | Overrides registry cache TTL (defaults to `300` seconds) \[11\].                          |
| `MEOW_INSTALL_TRACE`                | Read      | Prints precise micro-timings of resolution and installation phases \[11\].                |
| `MEOW_TSC`                          | Read      | Forces custom `tsc` binary target for type diagnostics \[11\].                            |
| `NODE_OPTIONS`                      | Read      | Extracts `--max-old-space-size` memory cap \[10, 11\].                                    |
| `MEOW_NODE_SHIM`                    | Written   | Set to `1` by meow inside children to track execution loops \[11\].                       |
| `MEOW_EXEC_PATH`                    | Written   | Holds absolute file path of active meow runner binary \[11\].                             |
| `NODE` / `npm_node_execpath`        | Written   | Paths targeting meow's virtual Node shims \[11\].                                         |

7. MODULE RESOLUTION & INTEROP

meow's resolver processes standard CommonJS and ESM imports [12].

Fixed Condition Resolution Priority

Unlike standard Node engines which resolve keys by insertion order, meow applies
a deterministic condition cascade [12]:

  - ESM Context: meow \to import \to node \to default [12]
  - CommonJS Context: meow \to require \to node \to default [12]

CommonJS / ESM Translators

If a module resolution format cannot be asserted deterministically, standard
Node CommonJS parsing is applied, with a fallback to the native ESM compiler
loop if syntax errors are returned during execution [12].

8. BUILT-IN MODULES (Namespace meow:*)

meow:http

Standard HTTP/1.1 server integration utilizing standard Web Request and Response
interfaces [25].

import { serve, Server, NetAddr } from "meow:http";

// Handler-first signature
const server1 = serve((req: Request) => new Response("hi"), { port: 3000 });

// Options-first Deno-style signature
const server2 = serve({
  port: 8080,
  hostname: "127.0.0.1",
  fetch: (req: Request) => Response.json({ status: "ok" }),
  onListen: (addr: NetAddr) => console.log(`Listening on ${addr.port}`)
});

// Server Interface
// interface Server {
//   readonly addr: NetAddr;
//   shutdown(): Promise<void>;
//   readonly finished: Promise<void>;
// }

meow:ui

Terminal output printer integrating with meow's UI rendering pipeline [27].
Automatic plain text fallback occurs in CI or non-interactive pipes [11, 27].

import { ui, purr, hiss, pounce } from "meow:ui";

ui.purr("Operation success");    // Renders success
ui.pounce("Running step...");    // Renders warning/in-progress
ui.hiss("Process failed");       // Renders error

meow:test

Test runner assertion target used by the meow test framework [28].

import { test, expect } from "meow:test";

test("suite label", () => {
  expect(1).toBe(1);                             // Identity equality via Object.is
  expect({ x: 1 }).toEqual({ x: 1 });            // Deep structural equality
  expect(null).toBeNull();
  expect(undefined).not.toBeDefined();
  expect(true).toBeTruthy();
  expect(false).toBeFalsy();
  expect(() => { throw new Error(); }).toThrow();
});

9. TYPESCRIPT COMPILATION PIPELINE

In-Place Type-Stripping

meow executes TypeScript without transpilation or code downleveling [14]. The
parser processes the document using Oxc [12] and replaces type annotations
directly with exact blank whitespace spans [14].

  - No Source Maps: Since byte offsets remain identical between the source
    document and the executed JS string, runtime stack traces natively align
    with the TS file [14].
  - Erasable Subset Restriction: The engine only supports erasable constructs
    [14]. Non-erasable features fail to compile [14]:
      - enum (Use const objects with union types instead) [14].
      - namespace definitions with values (Use standard ES modules) [14].
      - Constructor parameter property assignments (Declare fields explicitly)
        [14].
      - Experimental TypeScript decorators (Use clean wrapper functions) [14].

Module Extension Fallback

Standard TS code maps imports targeting .js files when the physical resource is
named .ts [14]. meow's resolver natively intercepts standard .js imports and
tests for TS alternatives (.ts, .tsx, .mts) before raising resolution errors
[14].

10. STATIC ANALYSIS & TOOLING

meow check

Launches the TypeScript compiler (tsc) over the generated .meow/tsconfig.json
compiler options [18]. Parses compilation errors and prints code frames
targeting the precise failing caret spans [18]. Re-fetches TypeScript
ephemerally if not installed in project scopes [18].

meow lint

Runs Oxc-powered static checks using the AST generated from the shared parse
pipeline [19].

  - Rule Configuration: Rule configurations map key-value severities from
    meow.config.json [1, 19]:
    { "lint": { "rules": { "no-debugger": "error", "no-unused-vars": "warn" } } }

meow fmt

Oxc code printer formatter [12, 20]. Contains no aesthetic layout modifiers
[20].

  - meow fmt [paths...]: Reformats documents in-place [20].
  - meow fmt --check: Validates formatting without writing. Returns exit code 1
    on unformatted matches [20].

meow bundle

Rolldown-powered bundler mapped over meow's internal module resolver [12, 16].

  - Scope Protection: Importer resolution blocks packages not explicitly
    declared in the project's dependency graph to prevent phantom imports [16].

11. OBSERVABILITY DIAGNOSTICS

meow why-dep <package>

Traces path permutations in meow.lock.jsonl mapping direct root entries down to
requested dependency [7]. Returns non-zero exit if target is absent [7].

  - Flags: --shortest (one path limit per version), --json (machine output),
    --limit <n> (path exploration cap) [7].

meow why-large

Reads local lockfile declarations and global cached directory metadata [17].
Prints size list of cached tarballs descending [7].

meow why-slow [target]

Analyzes startup times and logs cold-start system metrics [7].

meow doctor

Performs integrity sweeps over package.json, meow.lock.jsonl, local
node_modules, and state directories [7].

meow ls

Discovers live dev server ports via lsof (available on macOS and Linux) [7].
Formats known ports automatically [7]:

  - 3000: Next.js / React [7]
  - 4321: Astro [7]
  - 5173 / 4173: Vite / Vite Preview [7]
  - 1420: Tauri [7]
  - 8787: Wrangler [7]

12. CLI COMPLETE COMMAND & FLAG REFERENCE

Global Invariant Execution Arguments

These flags can be appended to any runtime execution command (run, dev, task, x)
[11, 19]:

  - --allow-clock: Grants access to real wall-clock, monotonic time, locale, and
    timezone settings [11, 19].
  - --allow-random: Grants access to native cryptographically secure OS entropy
    sources [11, 19].
  - --allow-env[=ALLOW_LIST]: Exposes host variables [11, 19]. Bare exposes all;
    comma-separated limits access to named keys [11].
  - --trust (alias MEOW_DANGEROUSLY_DISABLE_SECURITY=1): Activates all host
    access grants [11, 19].
  - --max-old-space-size <MiB>: Configures maximum V8 heap sizes [10, 19].
  - --v8-flags <flags>: Passes comma-separated arguments straight to the V8
    instance [19].

Command Directory & Argument Signatures

meow init [--mode <mode>] [--force] [--no-install]

Scaffolds meow.config.json [19], package.json [2], and main.ts [8]. Generates
shadow shims and runs installation (unless bypassed via --no-install) [19].

meow run <target> [-- <args...>]

Executes package script target or direct file path [10, 19]. Arguments parsed
after -- pass into standard argv arrays [10].

meow dev [-- <args...>]

Shorthand proxy executing meow run dev [10, 19].

meow task <name> [-- <args...>]

Explicit script executor bypassing path mapping resolution [10, 19].

meow test

Scans filesystem for *.(test|spec).(js|ts|jsx|tsx|mjs|mts|cjs|cts) and processes
each inside strict-web deterministic V8 isolates [19].

meow x <pkg> [args...]

Executes ephemeral command binary target [4, 19].

meow install [packages...] [-D|--dev] [-g|--global] [--vendor] [--vendor-dir <dir>] [--clean] [--compat-lockfile]

Installs dependency targets [17].

meow add <packages...> [-D|--dev] [-g|--global]

Adds new dependencies [17].

meow remove <packages...> [-g|--global]

Removes declared dependencies [17].

meow search <query> [-n|--limit <limit>] [--json]

Queries npm registry [17].

meow check [paths...]

Validates TypeScript type correctness [18].

meow lint [paths...]

Performs static analysis lint rules checks [18].

meow fmt [paths...] [--check]

Formats code documents [18].

meow bundle <entries...> [-o|--out <dir>]

Bundles ESM files using Rolldown [18].

meow why-dep <pkg> [--shortest] [--json] [--limit <n>]

Inspects lockfile dependency tree resolution vectors [17].

meow why-large

Traces large cached assets [17].

meow why-slow [target]

Traces application cold start characteristics [17].

meow doctor

Runs structural health checks [17].

meow sync

Forces regeneration of TS compiler interfaces and .meow/ configuration schemas
[17].

meow ls

Prints open development ports [17].