tina4-nodejs 3.13.92 → 3.13.94

package/types/core/src/middleware.d.ts

@@ -0,0 +1,207 @@
+import type { Tina4Request, Tina4Response, Middleware } from "./types.js";
+export declare class MiddlewareChain {
+    private middlewares;
+    use(fn: Middleware): void;
+    /**
+     * Run the chain in REGISTRATION order — each middleware runs exactly once,
+     * in the order it was attached via use(). The chain advances from ONE
+     * source only: `next()`. (The old runner double-advanced — a for-loop index
+     * AND next() both incremented — so every other middleware was silently
+     * skipped. Fixed by driving the chain purely by next(), mirroring Python's
+     * _make_mw_continuation Russian-doll continuation.)
+     *
+     * A middleware may stop the chain by:
+     *   - not calling next() (it owns the response), or
+     *   - ending the response (res.raw.writableEnded).
+     * Returns true when the whole chain ran to completion (handler may proceed),
+     * false when it was short-circuited.
+     */
+    run(req: Tina4Request, res: Tina4Response): Promise<boolean>;
+}
+export declare class MiddlewareRunner {
+    /** Globally registered middleware classes (parity with PHP/Ruby/Python orchestrators). */
+    private static globalMiddleware;
+    /**
+     * Register a middleware class to run on every request.
+     * Mirrors Tina4\Middleware::use (PHP), Tina4::Middleware.use (Ruby),
+     * and Middleware.use (Python).
+     */
+    static use(cls: any): void;
+    /** Return the list of globally registered middleware classes. */
+    static getGlobal(): any[];
+    /** Clear all globally registered middleware (primarily for tests). */
+    static reset(): void;
+    /**
+     * Discover the before-prefixed / after-prefixed method names on a
+     * middleware class in DEFINITION order (M1).
+     * `Object.getOwnPropertyNames` returns a class's own
+     * static method names in source-declaration order — we deliberately do NOT
+     * sort() them, so within a class the hooks run in the order they were
+     * written (parity with Python walking __dict__, PHP get_class_methods, Ruby
+     * instance_methods(false)). Cross-class order is the natural iteration of
+     * the registered classes = REGISTRATION order.
+     */
+    private static methodNames;
+    /**
+     * Execute every beforeX static method found on the supplied classes.
+     *
+     * ORDER (M1): cross-class = REGISTRATION order (the order classes were
+     * attached via Router.use / MiddlewareRunner.use); within a class =
+     * DEFINITION order (source order, never alphabetical). before_* run before
+     * the handler.
+     *
+     * THROW (M2): each before* call is wrapped — a throwing middleware is
+     * LOGGED and produces a deterministic clean 500 (it never crashes the
+     * worker / leaks an unhandled exception), and the chain short-circuits
+     * (skip = true, handler skipped).
+     *
+     * Short-circuits (skip = true, handler skipped) when a before* sets a
+     * status >= 400 or ends/500s the response.
+     *
+     * ASYNC — each hook is awaited so middleware can perform async work (e.g.
+     * the distributed responseCache before-hook awaiting `backend.get`). Awaiting
+     * a synchronous hook that returns an array is harmless (the array resolves
+     * immediately), so existing sync hooks keep working unchanged.
+     *
+     * Returns [req, res, shouldContinue].
+     */
+    static runBefore(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response, boolean]>;
+    /**
+     * Execute every afterX static method found on the supplied classes.
+     *
+     * ORDER (M1): cross-class = REGISTRATION order; within a class = DEFINITION
+     * order. after_* run after the handler.
+     *
+     * THROW (M2): each after* call is wrapped — a throwing after middleware is
+     * LOGGED and produces a clean 500, then the remaining after* STILL run
+     * (they may add headers / logging). No unhandled exception leaks.
+     *
+     * AFTER-ON-4xx RULE (M2): after_* ALWAYS run, even when a before_*
+     * short-circuited with status >= 400 and the handler was skipped — so they
+     * can still add headers / logging. The dispatcher calls runAfter
+     * unconditionally after the before/handler block (see server.ts).
+     *
+     * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
+     * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
+     * after-hooks keep working unchanged.
+     */
+    static runAfter(classes: any[], req: Tina4Request, res: Tina4Response): Promise<[Tina4Request, Tina4Response]>;
+}
+/** Configuration for the CORS middleware */
+export interface CorsConfig {
+    /** Allowed origins. Default: "*" (or TINA4_CORS_ORIGINS env, comma-separated) */
+    origins?: string | string[];
+    /** Allowed methods. Default: standard REST methods (or TINA4_CORS_METHODS env) */
+    methods?: string | string[];
+    /** Allowed headers. Default: Content-Type, Authorization (or TINA4_CORS_HEADERS env) */
+    headers?: string | string[];
+    /** Access-Control-Max-Age in seconds. Default: 86400 (or TINA4_CORS_MAX_AGE env) */
+    maxAge?: number;
+}
+/**
+ * Built-in CORS middleware (function form).
+ * Reads configuration from env vars if not provided:
+ *   TINA4_CORS_ORIGINS — comma-separated list of allowed origins, or "*"
+ *   TINA4_CORS_METHODS — comma-separated list of allowed methods
+ *   TINA4_CORS_HEADERS — comma-separated list of allowed headers
+ *   TINA4_CORS_MAX_AGE — preflight cache duration in seconds
+ *
+ * Preflight (OPTIONS) returns 204 with appropriate headers.
+ * Supports wildcard ("*") and specific origin matching.
+ */
+export declare function cors(config?: CorsConfig): Middleware;
+/**
+ * Class-based CORS middleware using the before/after convention.
+ * Wraps the same CORS logic as the `cors()` function middleware.
+ *
+ * Usage:
+ *   Router.use(CorsMiddleware);
+ */
+export declare class CorsMiddleware {
+    static beforeCors(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    /**
+     * Check if a request is an OPTIONS preflight.
+     */
+    static isPreflight(method: string): boolean;
+}
+/**
+ * Class-based rate limiter middleware using the before/after convention.
+ * Uses the same sliding-window algorithm as the `rateLimiter()` function.
+ *
+ * Reads configuration from env vars:
+ *   TINA4_RATE_LIMIT  — max requests per window (default 100)
+ *   TINA4_RATE_WINDOW — window duration in seconds (default 60)
+ *
+ * Usage:
+ *   Router.use(RateLimiterMiddleware);
+ */
+export declare class RateLimiterMiddleware {
+    private static store;
+    private static cleanupTimer;
+    private static ensureCleanup;
+    static beforeRateLimit(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    /**
+     * Check if an IP is within rate limits without recording a request.
+     * Returns [allowed, info] matching Python/Ruby API.
+     */
+    static check(ip: string): [boolean, {
+        limit: number;
+        remaining: number;
+        reset: number;
+        window: number;
+    }];
+}
+/**
+ * Class-based request logger middleware using the before/after convention.
+ * `beforeLog` stamps the request start time.
+ * `afterLog` prints the coloured status line.
+ *
+ * Usage:
+ *   Router.use(RequestLogger);
+ */
+export declare class RequestLogger {
+    static beforeLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+    static afterLog(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+/**
+ * Class-based security headers middleware using the before/after convention.
+ * Auto-injects security headers on every response.
+ *
+ * Configuration via env vars:
+ *   TINA4_FRAME_OPTIONS       — X-Frame-Options (default: "SAMEORIGIN")
+ *   TINA4_HSTS                — Strict-Transport-Security max-age value
+ *                                (default: "" = off; set to "31536000" to enable)
+ *   TINA4_CSP                 — Content-Security-Policy (default: "default-src 'self'")
+ *   TINA4_REFERRER_POLICY     — Referrer-Policy (default: "strict-origin-when-cross-origin")
+ *   TINA4_PERMISSIONS_POLICY  — Permissions-Policy (default: "camera=(), microphone=(), geolocation=()")
+ *
+ * Usage:
+ *   Router.use(SecurityHeadersMiddleware);
+ */
+export declare class SecurityHeadersMiddleware {
+    static beforeSecurity(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+/**
+ * Class-based CSRF middleware using the before/after convention.
+ * Validates form tokens on state-changing requests (POST, PUT, PATCH, DELETE).
+ *
+ * Off by default — only active when TINA4_CSRF=true in .env or when
+ * registered explicitly via Router.use(CsrfMiddleware).
+ *
+ * Behaviour:
+ *   - Skips GET, HEAD, OPTIONS requests.
+ *   - Skips routes marked .noAuth().
+ *   - Skips requests with a valid Authorization: Bearer header (API clients).
+ *   - Checks request body formToken then X-Form-Token header.
+ *   - Rejects if token found in query string formToken (log warning, 403).
+ *   - Validates token with validToken using SECRET env var.
+ *   - If token payload has session_id, verifies it matches request session.
+ *   - Returns 403 on failure.
+ *
+ * Usage:
+ *   Router.use(CsrfMiddleware);
+ */
+export declare class CsrfMiddleware {
+    static beforeCsrf(req: Tina4Request, res: Tina4Response): [Tina4Request, Tina4Response];
+}
+export declare function requestLogger(): Middleware;

package/types/core/src/mqtt.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Zero-dependency MQTT 3.1.1 client — the protocol every broker and every IoT
+ * device already speaks.
+ *
+ * Built on Node's `node:net` and `node:tls` stdlib modules only: no npm package,
+ * so an app that talks to Mosquitto / EMQX / HiveMQ / AWS IoT adds nothing to its
+ * dependency tree. Shaped like the Queue on purpose — publish / subscribe /
+ * consume:
+ *
+ *     import { Mqtt } from "@tina4stack/tina4-node";
+ *
+ *     const mqtt = new Mqtt({ url: "mqtt://broker:1883" });   // TINA4_MQTT_URL
+ *     await mqtt.connect();
+ *     await mqtt.publish("fleet/meter-42/telemetry", '{"kwh":12.5}', 1);
+ *
+ *     for await (const message of mqtt.consume("fleet/+/telemetry", 1)) {
+ *       if (message.isDuplicate()) continue;                  // QoS 1 is at-least-once
+ *       store(message.topic, message.payload);
+ *     }
+ *
+ * Environment: TINA4_MQTT_URL (default mqtt://127.0.0.1:1883),
+ * TINA4_MQTT_CLIENT_ID, TINA4_MQTT_KEEPALIVE (seconds, default 60),
+ * TINA4_MQTT_CA_FILE, TINA4_MQTT_TLS_VERIFY.
+ *
+ * Node has no synchronous blocking socket read, so connect()/publish()/
+ * subscribe()/receive() are async and consume() is an async generator — the same
+ * idiom as the Queue. No background task runs by default; opt in to the
+ * cooperative keepalive with startKeepalive(), which registers a background()
+ * task exactly like the queue consumers do.
+ *
+ * Single reader: like every MQTT client the socket has ONE network reader. Call
+ * receive()/consume() from one place.
+ */
+import { MqttMessage } from "./mqttMessage.js";
+/** Any MQTT protocol / connection failure. */
+export declare class MqttError extends Error {
+    constructor(message: string);
+}
+/** The broker did not answer inside the timeout. */
+export declare class MqttTimeoutError extends MqttError {
+    constructor(message: string);
+}
+export interface MqttOptions {
+    url?: string;
+    clientId?: string;
+    username?: string;
+    password?: string;
+    caFile?: string;
+    tlsVerify?: boolean;
+    keepalive?: number;
+    cleanSession?: boolean;
+    willTopic?: string;
+    willPayload?: unknown;
+    willQos?: number;
+    willRetain?: boolean;
+    /** Seconds to wait for a control-packet answer (CONNACK / PUBACK / SUBACK). */
+    timeout?: number;
+    /** Seconds to wait for an application message; null/undefined blocks. */
+    readTimeout?: number | null;
+}
+export interface ParsedMqttUrl {
+    host: string;
+    port: number;
+    tls: boolean;
+    username: string | null;
+    password: string | null;
+}
+export declare class Mqtt {
+    readonly host: string;
+    readonly port: number;
+    readonly clientId: string;
+    readonly keepalive: number;
+    readonly cleanSession: boolean;
+    readonly username: string | null;
+    private readonly secure;
+    private readonly password;
+    private readonly caFile;
+    private readonly tlsVerify;
+    private readonly willTopic;
+    private readonly willPayload;
+    private readonly willQos;
+    private readonly willRetain;
+    private readonly timeout;
+    private readonly readTimeout;
+    private packetId;
+    private inbox;
+    private lastWriteAt;
+    private socket;
+    private keepaliveTask;
+    private readBuffer;
+    private waiter;
+    private socketError;
+    constructor(options?: MqttOptions);
+    /**
+     * Split an MQTT url into { host, port, tls, username, password }.
+     *
+     * "mqtt://host:port" and "tcp://host:port" are plain TCP (default port 1883);
+     * "mqtts://host:port" is TLS (default 8883). A bare "host" or "host:port"
+     * works too, and an IPv6 literal is bracketed ("mqtt://[::1]:1883").
+     * Credentials ride in the userinfo and are percent-decoded, so a password
+     * containing @ : or / survives.
+     */
+    static parseUrl(url: string): ParsedMqttUrl;
+    /**
+     * Decode %XX in url userinfo. NOT decodeURI-style "+"-to-space: a "+" in a
+     * password must survive verbatim, and an invalid "%" is left as-is (never throws).
+     */
+    private static percentDecode;
+    /**
+     * Remaining Length varint: 7 bits per byte, high bit means "another byte
+     * follows". A single-byte assumption works for every packet under 128 bytes
+     * and then fails, so this is exercised directly at 0 / 127 / 128 / 16383.
+     */
+    static encodeRemainingLength(value: number): Buffer;
+    /**
+     * Open the socket and complete the CONNECT / CONNACK handshake. Also the
+     * reconnect path: an existing socket is closed first, and a durable session
+     * (cleanSession false) resumes with the same clientId. Returns this for
+     * chaining (`const c = await new Mqtt(opts).connect()`).
+     */
+    connect(): Promise<this>;
+    /** Whether a socket is currently open. */
+    connected(): boolean;
+    /** True when this connection runs over TLS (mqtts://). */
+    tls(): boolean;
+    /**
+     * The negotiated cipher suite name, or null on a plain connection. A real name
+     * here is proof the TLS handshake actually completed.
+     */
+    cipher(): string | null;
+    /** The negotiated TLS protocol version ("TLSv1.3"), or null when plain. */
+    tlsVersion(): string | null;
+    /**
+     * Publish an application message. Resolves to the packet identifier for QoS 1
+     * (the broker's PUBACK must carry it back) and null for QoS 0.
+     *
+     * retain=true tells the broker to keep this as the topic's last known value and
+     * hand it to every FUTURE subscriber. Publishing an EMPTY payload with
+     * retain=true clears a retained value.
+     */
+    publish(topic: string, payload: unknown, qos?: number, retain?: boolean): Promise<number | null>;
+    /**
+     * Subscribe to a topic filter ("fleet/+/telemetry", "fleet/#"). Resolves to the
+     * QoS the broker GRANTED, which can be lower than requested.
+     *
+     * A SUBACK carrying 0x80 is a REFUSAL, not a success -- treating any SUBACK as
+     * success means sitting on a dead subscription receiving nothing, so it throws.
+     */
+    subscribe(topicFilter: string, qos?: number): Promise<number>;
+    /**
+     * Read the next application message.
+     *
+     * ack=true (the default) acknowledges a QoS 1 delivery immediately, which is
+     * right for a synchronous read. Pass ack=false when the message must be stored
+     * before the broker is allowed to forget it -- an unacknowledged QoS 1 message
+     * is redelivered with DUP set. consume() does exactly that.
+     */
+    receive(timeout?: number | null, ack?: boolean): Promise<MqttMessage>;
+    /**
+     * Long-running consumer, mirroring Queue.consume().
+     *
+     *     for await (const message of mqtt.consume("fleet/+/telemetry", 1)) {
+     *       store(message);
+     *     }
+     *
+     * The message is acknowledged AFTER the loop body hands control back to the
+     * generator (the next iteration), so a body that throws leaves the message
+     * unacknowledged and the broker redelivers it with DUP set -- at-least-once,
+     * the point of QoS 1. iterations > 0 stops after that many messages.
+     */
+    consume(topicFilter?: string | null, qos?: number, iterations?: number, timeout?: number | null): AsyncGenerator<MqttMessage>;
+    /** PUBACK a QoS 1 delivery. Called by MqttMessage.acknowledge(). */
+    acknowledge(packetId: number): Promise<boolean>;
+    /**
+     * PINGREQ and wait for the PINGRESP. Use this when nothing else is reading the
+     * socket; under a consume loop use startKeepalive() instead.
+     */
+    ping(timeout?: number | null): Promise<boolean>;
+    /**
+     * Write a PINGREQ without waiting for the answer. The PINGRESP is absorbed by
+     * whatever is reading the socket (receive() skips it).
+     */
+    sendKeepalive(): Promise<boolean>;
+    /**
+     * Opt in to the cooperative keepalive. Registers a background() task -- the
+     * same mechanism the queue consumers use -- that sends a PINGREQ only when the
+     * connection has gone quiet, so an actively publishing client costs no extra
+     * packets.
+     */
+    startKeepalive(intervalSeconds?: number): {
+        stop: () => void;
+    };
+    /** Stop the cooperative keepalive registered by startKeepalive(). */
+    stopKeepalive(): boolean;
+    /**
+     * Say goodbye properly: DISCONNECT then close. The broker discards the Last
+     * Will on a graceful disconnect.
+     */
+    disconnect(): Promise<boolean>;
+    /**
+     * Drop the socket WITHOUT a DISCONNECT -- what a crashed or unplugged device
+     * looks like to the broker, and therefore what fires the Last Will.
+     */
+    kill(): boolean;
+    private connectFlags;
+    /**
+     * Open a connected socket, upgrading to TLS when mqtts://. Rejects with an
+     * MqttError on a connect timeout or a TLS verification failure (the cert error
+     * message is preserved so a rejected cert reports WHY). Each connection builds
+     * its OWN tls options object, so a CA supplied for one client never leaks into
+     * a later client.
+     */
+    private openSocket;
+    private refuseUnsupportedQos;
+    /** Encode an MQTT string: a 2-byte big-endian length followed by UTF-8 bytes. */
+    private static mqttString;
+    private static uint16;
+    private static payloadBytes;
+    /** The next packet identifier (1..65535; 0 is invalid). */
+    private nextPacketId;
+    private writePacket;
+    /**
+     * Read one control packet. The fixed header is read in exactly 1 + N bytes
+     * (N <= 4 for the varint) so the next packet's header is never consumed by a
+     * speculative over-read.
+     */
+    private readPacket;
+    /**
+     * Read exactly `need` bytes from the socket buffer, awaiting more data when
+     * short. Only one read is ever outstanding (the protocol reads sequentially),
+     * so a single waiter slot is enough. The 'data' handler feeds the buffer and
+     * services the waiter; a deadline arms a timer that rejects with a timeout.
+     */
+    private readExact;
+    private take;
+    private serviceWaiter;
+    private onData;
+    private onSocketGone;
+    /** Read packets until the next PUBLISH, skipping keepalive PINGRESPs. */
+    private readPublish;
+    /**
+     * Park a PUBLISH that arrives while we wait for a PUBACK/SUBACK/PINGRESP
+     * (normal when the same connection both publishes and subscribes) so receive()
+     * still delivers it, in order, instead of it being mistaken for the ack.
+     */
+    private stashPublish;
+    private parsePublish;
+    /**
+     * Wait for a specific acknowledgement, tolerating interleaved PUBLISH and
+     * PINGRESP packets. A mismatched packet identifier is silent data loss if
+     * ignored, so it throws.
+     */
+    private waitForAcknowledgement;
+    private idleFor;
+    private deadlineIn;
+    private closeSocket;
+}

package/types/core/src/mqttMessage.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One MQTT 3.1.1 application message as delivered by the broker.
+ *
+ * Shaped like the Queue's job (its unit of work): it carries the payload plus
+ * the delivery metadata a consumer needs, and it knows how to acknowledge itself
+ * back to the client it came from. Mirrors tina4_python.mqtt.MqttMessage,
+ * Tina4::MqttMessage (Ruby), and Tina4\MqttMessage (PHP).
+ *
+ * The two flags matter for correctness, not decoration:
+ *
+ *   retained  — the broker replayed the topic's last known value to us because
+ *               we subscribed AFTER it was published. It is current state, not a
+ *               fresh event.
+ *   duplicate — the DUP flag. The broker is REDELIVERING a QoS 1 message it never
+ *               saw acknowledged. QoS 1 is at-least-once, so a duplicate is
+ *               guaranteed eventually; a consumer that treats a DUP delivery as a
+ *               new sample double-counts energy or mileage. Key the ingest on
+ *               (deviceId, deviceTimestamp) and it is harmless.
+ *
+ * The payload is a Buffer of the raw bytes; text() decodes it for JSON/string
+ * payloads.
+ */
+/** The slice of an Mqtt client an MqttMessage needs to acknowledge itself. */
+export interface MqttAcknowledger {
+    acknowledge(packetId: number): Promise<boolean>;
+}
+export declare class MqttMessage {
+    readonly topic: string;
+    readonly payload: Buffer;
+    readonly qos: number;
+    readonly retained: boolean;
+    readonly duplicate: boolean;
+    readonly packetId: number | null;
+    private readonly client;
+    private acknowledgedFlag;
+    constructor(topic: string, payload: Buffer, qos?: number, retained?: boolean, duplicate?: boolean, packetId?: number | null, client?: MqttAcknowledger | null);
+    /** True when the broker replayed this as the topic's retained (last known) value. */
+    isRetained(): boolean;
+    /**
+     * True when the broker set the DUP flag — a REDELIVERY of a QoS 1 message we
+     * never acknowledged, not a new sample.
+     */
+    isDuplicate(): boolean;
+    /**
+     * PUBACK a QoS 1 delivery so the broker stops redelivering it.
+     *
+     * A QoS 0 message needs no acknowledgement, and a second call is a no-op, so
+     * this is always safe to call once processing succeeded. Returns true only
+     * when a PUBACK was actually sent.
+     */
+    acknowledge(): Promise<boolean>;
+    /** True once this message has been acknowledged back to the broker. */
+    isAcknowledged(): boolean;
+    /** The payload decoded as text (for JSON / string payloads). */
+    text(encoding?: BufferEncoding): string;
+    /** The message as a plain object. */
+    toObject(): {
+        topic: string;
+        payload: Buffer;
+        qos: number;
+        retained: boolean;
+        duplicate: boolean;
+        packetId: number | null;
+    };
+    /** String form is the payload text (parity with Python __str__ / Ruby to_s). */
+    toString(): string;
+}

package/types/core/src/plan.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Project plan management — persistent, human-readable task state.
+ *
+ * Ported from tina4_python/dev_admin/plan.py (master reference).
+ * A plan is a markdown file under plan/ at the project root with sections
+ * for title, goal, steps (checkboxes), and notes. Exactly one plan is
+ * "current" at a time, recorded in plan/.current.
+ *
+ * Byte-for-byte compatible with Python's plan/*.md storage.
+ */
+export interface PlanStep {
+    text: string;
+    done: boolean;
+    index?: number;
+}
+export interface ParsedPlan {
+    title: string;
+    goal: string;
+    steps: PlanStep[];
+    notes: string;
+}
+export interface PlanSummary {
+    name: string;
+    title: string;
+    steps_total: number;
+    steps_done: number;
+    is_current: boolean;
+    /** Path relative to project root — lets the SPA open the right file
+     *  regardless of which dir the plan came from (plan/ vs .tina4/plans/). */
+    path: string;
+}
+export interface ExecutionSummary {
+    created: string[];
+    patched: string[];
+    migrations: string[];
+    total: number;
+}
+export interface CurrentPlan {
+    current: string | null;
+    title?: string;
+    goal?: string;
+    steps?: PlanStep[];
+    next_step?: PlanStep | null;
+    notes?: string;
+    progress?: {
+        done: number;
+        total: number;
+    };
+    execution?: ExecutionSummary;
+    warning?: string;
+}
+export declare const Plan: {
+    /**
+     * All plan files — merged from `plan/` (user-curated canonical) and
+     * `.tina4/plans/` (where the Rust supervisor's planner writes).
+     *
+     * Two directories exist because of a historic split: the framework
+     * treats `plan/` as the canonical project location, but the Rust agent's
+     * planner writes to `.tina4/plans/` (alongside other AI-state artefacts
+     * like chat history). Until those are unified we read both so plans
+     * created either way are discoverable. Dedup by filename when a plan
+     * exists in both — `plan/` wins on collision.
+     *
+     * Newest-first by filename (Rust planner uses unix-timestamp prefixes).
+     */
+    listPlans(): PlanSummary[];
+    currentName(): string;
+    setCurrent(name: string): {
+        ok: boolean;
+        current?: string;
+        error?: string;
+    };
+    clearCurrent(): {
+        ok: boolean;
+    };
+    current(): CurrentPlan;
+    read(name: string): ParsedPlan & {
+        name?: string;
+        error?: string;
+    };
+    create(title: string, goal?: string, steps?: string[], makeCurrent?: boolean): {
+        ok: boolean;
+        name?: string;
+        title?: string;
+        is_current?: boolean;
+        error?: string;
+    };
+    completeStep(index: number, name?: string): Record<string, unknown>;
+    uncompleteStep(index: number, name?: string): Record<string, unknown>;
+    addStep(text: string, name?: string): Record<string, unknown>;
+    appendNote(text: string, name?: string): Record<string, unknown>;
+    recordAction(action: string, filePath: string, note?: string): void;
+    summariseExecution(name?: string): ExecutionSummary;
+    flesh(name?: string, prompt?: string): Promise<Record<string, unknown>>;
+    archive(name?: string): Record<string, unknown>;
+};

package/types/core/src/projectIndex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Project index — lightweight, persistent "where is what" map.
+ *
+ * Ported from tina4_python/dev_admin/project_index.py (master reference).
+ *
+ * Storage: .tina4/project_index.json at the project root.
+ * Freshness: lazy-refreshes on read via mtime compare — no watchers.
+ * Extractors: per-language symbol extraction (TS/JS, Twig/HTML, SQL, Markdown,
+ * Python) using regex. No LLM involvement — pure static analysis.
+ */
+export interface FileRoute {
+    method: string;
+    path: string;
+    handler: string;
+}
+export interface FileEntry {
+    path?: string;
+    size?: number;
+    mtime?: number;
+    language?: string;
+    sha256?: string;
+    skipped?: string;
+    extraction_error?: string;
+    summary?: string;
+    symbols?: string[];
+    imports?: string[];
+    routes?: FileRoute[];
+    docstring?: string;
+    exports?: string[];
+    extends?: string[];
+    blocks?: string[];
+    includes?: string[];
+    creates?: string[];
+    alters?: string[];
+    title?: string;
+    sections?: string[];
+    first_line?: string;
+    error?: string;
+}
+export declare const ProjectIndex: {
+    refresh(): {
+        added: number;
+        updated: number;
+        removed: number;
+        total: number;
+        path: string;
+    };
+    search(query: string, limit?: number): Array<{
+        path: string;
+        summary: string;
+        score: number;
+        language: string;
+    }>;
+    fileEntry(relPath: string): FileEntry;
+    overview(): Record<string, unknown>;
+};