attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/types.d.ts

@@ -0,0 +1,371 @@
+import type { Charset } from "../syntax/types.js";
+import type { OutlineResult } from "../outline/types.js";
+export type { OutlineKind, OutlineCategory, OutlineRange, OutlineType, OutlineNode, OutlineResult, WireOutlineRange, WireOutlineNode, WireOutlineResult } from "../outline/types.js";
+/**
+ * Filesystem domain types.
+ *
+ * The model is deliberately tree-first. A directory owns an ordered set of
+ * `File`/`Directory` nodes; a file has no children. Every node carries the
+ * metadata an agent needs to decide whether to read it before paying for the
+ * content: a content fingerprint, charset, line/byte counts, timestamps and a
+ * short description/summary/purpose.
+ *
+ * The in-process shape uses `bigint` for `lines` and `bytes` so a large tree
+ * cannot silently lose precision. JSON has no bigint, so the wire projection
+ * (`WireTreeNode`) spells the same values as decimal strings; both forms are
+ * part of the public contract.
+ */
+import type { SessionRoot } from "../session/types.js";
+/**
+ * Charset detected for a node. Directories use `none`; files that do not
+ * decode as UTF-8/UTF-16 and do not look like text use `binary`.
+ */
+export type { Charset } from "../syntax/types.js";
+/**
+ * Timestamp format used by node metadata: `yyyy-MM-ddTHH:mm:ss` with no zone
+ * suffix. The filesystem service defaults to host-local wall time because that
+ * is what a user sees in an explorer; hosts that need reproducible snapshots
+ * can request UTC.
+ */
+export type NodeTime = string;
+/**
+ * `Date.toISOString()`-shaped timestamp used by protocol envelopes, audits and
+ * persistence rows. Node metadata uses the shorter `NodeTime` form.
+ */
+export type IsoTime = string;
+/**
+ * Host-supplied, path-keyed override of the derived metadata. An override is
+ * descriptive only: it never changes access checks or the content fingerprint.
+ */
+export interface NodeAnnotation {
+    readonly description?: string;
+    readonly summary?: string;
+    readonly purpose?: string;
+}
+/**
+ * Metadata shared by files and directories. `fingerprint` is a content-address
+ * ref: `sha256:<hex>` of the file bytes, or a domain-separated Merkle digest of
+ * the sorted child refs for a directory.
+ */
+export interface NodeMetadata {
+    readonly fingerprint: string;
+    readonly charset: Charset;
+    readonly lines: bigint;
+    readonly bytes: bigint;
+    readonly create: NodeTime;
+    readonly modify: NodeTime;
+    readonly description: string;
+    readonly summary: string;
+    readonly purpose: string;
+}
+/**
+ * Leaf node. `children` is always the empty tuple, which makes the tree shape
+ * checkable by the type system rather than by a convention.
+ */
+export interface FileNode extends NodeMetadata {
+    readonly type: "File";
+    readonly path: string;
+    readonly name: string;
+    readonly extension: string;
+    readonly children: readonly [];
+}
+/**
+ * Interior node. `bytes`/`lines` aggregate descendants; `modify` is the latest
+ * descendant modification so a directory answers "when did this subtree last
+ * change?" without walking it again.
+ */
+export interface DirectoryNode extends NodeMetadata {
+    readonly type: "Directory";
+    readonly path: string;
+    readonly name: string;
+    readonly extension: "directory";
+    readonly children: readonly TreeNode[];
+}
+/**
+ * Any tree node.
+ */
+export type TreeNode = FileNode | DirectoryNode;
+/**
+ * Derived node statistics used by service limits without re-walking the tree.
+ */
+export interface TreeStats {
+    readonly files: bigint;
+    readonly directories: bigint;
+    readonly lines: bigint;
+    readonly bytes: bigint;
+    readonly truncated: boolean;
+}
+/**
+ * Options that bound a tree build. `maxNodes` and `maxBytes` stop the walk with
+ * `truncated: true` instead of exhausting memory; callers can then list a
+ * subtree or raise the bound explicitly.
+ */
+export interface TreeOptions {
+    readonly maxNodes?: number;
+    readonly maxBytes?: bigint;
+    readonly exclude?: readonly string[];
+    readonly annotations?: Readonly<Record<string, NodeAnnotation>>;
+    readonly followSymlinks?: boolean;
+    readonly timeZone?: "local" | "utc";
+    readonly includeHidden?: boolean;
+}
+/**
+ * Snapshot returned by a tree build. `revision` changes whenever a node's
+ * fingerprint, annotation or child set changes.
+ */
+export interface TreeSnapshot {
+    readonly root: DirectoryNode;
+    readonly revision: string;
+    readonly stats: TreeStats;
+}
+/**
+ * Wire projection of a node. Lines and bytes are decimal strings because JSON
+ * cannot represent `bigint`; a reader parses them with `BigInt`.
+ */
+export interface WireFileNode extends Omit<FileNode, "children" | "lines" | "bytes"> {
+    readonly children: readonly [];
+    readonly lines: string;
+    readonly bytes: string;
+}
+/**
+ * Wire projection of a directory node.
+ */
+export interface WireDirectoryNode extends Omit<DirectoryNode, "children" | "lines" | "bytes"> {
+    readonly children: readonly WireTreeNode[];
+    readonly lines: string;
+    readonly bytes: string;
+}
+/**
+ * Wire node union.
+ */
+export type WireTreeNode = WireFileNode | WireDirectoryNode;
+/**
+ * A bounded directory listing. `nextOffset` is null when the page is complete.
+ */
+export interface DirectoryListing {
+    readonly path: string;
+    readonly revision: string;
+    readonly entries: readonly WireTreeNode[];
+    readonly total: number;
+    readonly nextOffset: number | null;
+}
+/**
+ * Read request. Offsets are 1-based line numbers; `maxBytes` bounds the decoded
+ * text and `maxLines` bounds the line count. `startLine > 1` costs a scan to
+ * that line, so a caller paging a huge file should keep the page size stable.
+ */
+export interface ReadRequest {
+    readonly path: string;
+    readonly startLine?: number;
+    readonly maxLines?: number;
+    readonly maxBytes?: number;
+    readonly includeLineNumbers?: boolean;
+}
+/**
+ * One bounded read page. `nextStartLine` is null at EOF. `text` is decoded with
+ * the node charset; binary files are refused before any text is produced.
+ */
+export interface ReadPage {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly charset: Charset;
+    readonly offset: number;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly totalLines: bigint;
+    readonly bytesRead: number;
+    readonly totalBytes: bigint;
+    readonly text: string;
+    readonly nextStartLine: number | null;
+    readonly truncated: boolean;
+    readonly binary: boolean;
+}
+/**
+ * Write mode. `create` fails when the file exists, `overwrite` requires an
+ * existing file, and `upsert` does either. CAS via `expectFingerprint` is an
+ * additional guard on top of the mode.
+ */
+export type WriteMode = "create" | "overwrite" | "upsert" | "append";
+/**
+ * Write request. When `expectFingerprint` is present the write is rejected
+ * unless the current file still has that fingerprint; `null` means "expect no
+ * file". `dryRun` runs every check and returns the projected node without
+ * touching the disk.
+ */
+export interface WriteRequest {
+    readonly path: string;
+    readonly content: string | Uint8Array;
+    readonly encoding?: "utf-8" | "utf-8-bom" | "utf-16le" | "utf-16be" | "latin1";
+    readonly mode?: WriteMode;
+    readonly expectFingerprint?: string | null;
+    readonly createParents?: boolean;
+    readonly dryRun?: boolean;
+}
+/**
+ * Result of a successful (or dry-run) write.
+ */
+export interface WriteResult {
+    readonly node: FileNode;
+    readonly previousFingerprint: string | null;
+    readonly created: boolean;
+    readonly dryRun: boolean;
+    readonly bytesWritten: bigint;
+    readonly revision: string;
+}
+/**
+ * Journal record for one successful write. The journal is metadata only; the
+ * previous bytes are recoverable from the object store/CAS when the host keeps
+ * one, so this module does not duplicate file content.
+ */
+export interface WriteJournalEntry {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly rootId: string;
+    readonly path: string;
+    readonly mode: WriteMode;
+    readonly previousFingerprint: string | null;
+    readonly nextFingerprint: string;
+    readonly bytes: bigint;
+    readonly at: IsoTime;
+}
+/**
+ * Import edge kinds. `export-from` is tracked because a re-export is still a
+ * dependency edge even though it is not an import statement.
+ */
+export type ImportKind = "static" | "dynamic" | "require" | "export-from" | "type";
+/**
+ * One module edge. `from` and `to` are root-relative POSIX paths; `to` is the
+ * resolved path for internal edges and the bare specifier for external ones.
+ */
+export interface ImportEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly specifier: string;
+    readonly kind: ImportKind;
+    readonly line: number;
+    readonly resolved: boolean;
+    readonly external: boolean;
+}
+/**
+ * Import report for one file. `importedBy` is the reverse edge list, which is
+ * what makes "who breaks if I change this?" cheap.
+ */
+export interface ImportReport {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly imports: readonly ImportEdge[];
+    readonly importedBy: readonly ImportEdge[];
+    readonly external: readonly string[];
+    readonly unresolved: readonly string[];
+    readonly truncated: boolean;
+}
+/**
+ * Exported symbol kinds.
+ */
+export type ExportKind = "function" | "class" | "interface" | "type" | "enum" | "const" | "let" | "var" | "default" | "namespace" | "reexport";
+/**
+ * One exported symbol with its source range and a bounded signature.
+ */
+export interface ExportSymbol {
+    readonly name: string;
+    readonly kind: ExportKind;
+    readonly line: number;
+    readonly signature: string;
+    readonly reexportFrom?: string;
+}
+/**
+ * Export report for one file.
+ */
+export interface ExportReport {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly exports: readonly ExportSymbol[];
+    readonly reexports: readonly ImportEdge[];
+    readonly truncated: boolean;
+}
+/**
+ * Node role in a dependency graph. Packages are included so a workspace file
+ * can depend on an external package without pretending it is a source file.
+ */
+export type DependencyNodeKind = "file" | "directory" | "package";
+/**
+ * One dependency graph node.
+ */
+export interface DependencyNode {
+    readonly id: string;
+    readonly path: string;
+    readonly kind: DependencyNodeKind;
+    readonly fingerprint: string;
+}
+/**
+ * Dependency edge kinds. `import`/`export`/`reference` come from source facts;
+ * `package` comes from a manifest declaration.
+ */
+export type DependencyEdgeKind = "import" | "export" | "reference" | "package";
+/**
+ * One directed dependency edge. `to` is a node id, not necessarily a path.
+ */
+export interface DependencyEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: DependencyEdgeKind;
+    readonly specifier?: string;
+    readonly line?: number;
+}
+/**
+ * Graph query mode. `cycles` returns strongly connected components with more
+ * than one node; `topological` returns a deterministic order or the blocking
+ * SCCs when the graph is cyclic.
+ */
+export type DependencyMode = "cycles" | "topological" | "dependencies" | "dependents" | "closure";
+/**
+ * Bounded dependency report. `order` is present for `topological`; `cycles`
+ * is present for `cycles` (and for a cyclic topological request).
+ */
+export interface DependencyReport {
+    readonly revision: string;
+    readonly mode: DependencyMode;
+    readonly roots: readonly string[];
+    readonly nodes: readonly DependencyNode[];
+    readonly edges: readonly DependencyEdge[];
+    readonly order: readonly string[];
+    readonly cycles: readonly (readonly string[])[];
+    readonly unresolved: readonly string[];
+    readonly external: readonly string[];
+    readonly truncated: boolean;
+}
+/**
+ * Errors are classified so a transport can map them to stable tool error codes
+ * without parsing messages. Every message is code-only, mirroring the existing
+ * workspace service: host paths never leak through an error string.
+ */
+export type FilesystemErrorCode = "invalid_arguments" | "session_unavailable" | "permission_denied" | "invalid_path" | "path_escape" | "symlink_denied" | "excluded_path" | "not_found" | "not_file" | "not_directory" | "already_exists" | "binary_file" | "charset_unsupported" | "fingerprint_mismatch" | "lock_conflict" | "quota_exceeded" | "parse_failed" | "store_failure" | "internal_error";
+/**
+ * Persistence port for the filesystem domain. The SQLite adapter implements
+ * this; the service itself only sees the port so the tree can also run in
+ * memory for tests and one-shot CLI use.
+ */
+export interface FilesystemStore {
+    loadTree(rootId: string): TreeSnapshot | undefined;
+    saveTree(rootId: string, snapshot: TreeSnapshot): void;
+    loadAnnotations(rootId: string): Record<string, NodeAnnotation>;
+    saveAnnotation(rootId: string, path: string, annotation: NodeAnnotation, source: string): void;
+    appendWrite(entry: WriteJournalEntry): void;
+    listWrites(sessionId: string, limit: number): WriteJournalEntry[];
+    loadOutline(rootId: string, path: string, fingerprint: string): OutlineResult | undefined;
+    saveOutline(rootId: string, outline: OutlineResult): void;
+    loadImports(rootId: string, path: string, fingerprint: string): ImportReport | undefined;
+    saveImports(rootId: string, report: ImportReport): void;
+    loadExports(rootId: string, path: string, fingerprint: string): ExportReport | undefined;
+    saveExports(rootId: string, report: ExportReport): void;
+    loadDependencyRevision(rootId: string): string | undefined;
+    saveDependencyRevision(rootId: string, revision: string): void;
+}
+/**
+ * Resolved path within one session root.
+ */
+export interface RootedPath {
+    readonly root: SessionRoot;
+    readonly relative: string;
+    readonly absolute: string;
+}

package/lib/file/types.js

@@ -0,0 +1 @@
+export {};

package/lib/file/write.d.ts

@@ -0,0 +1,159 @@
+import type { PathSandbox } from "./path.js";
+import type { RootedPath, WriteJournalEntry, WriteRequest, WriteResult } from "./types.js";
+import type { WorkspaceTree } from "./tree.js";
+/**
+ * Options for {@link writeFile}.
+ *
+ * `maxBytes` bounds the *resulting* file size, not the incoming fragment; an
+ * append is checked against the old size plus the new bytes. `journal` receives
+ * one metadata record per successful non-dry write. `tree` is refreshed after
+ * the rename so a workspace snapshot cannot keep the old fingerprint.
+ */
+export interface WriteOptions {
+    readonly maxBytes?: number;
+    readonly journal?: (entry: WriteJournalEntry) => void;
+    readonly tree?: WorkspaceTree;
+    readonly timeZone?: "local" | "utc";
+}
+/**
+ * Write locks keyed by `(sessionId, rootId, relativePath)`.
+ *
+ * The class is exported so a host can own one registry and share it with other
+ * workspace components; {@link writeFile} uses a process-wide registry because
+ * its frozen signature carries no lock parameter.
+ */
+export declare class WriteLocks {
+    private readonly locks;
+    run<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Number of distinct lock names seen so far.
+     */
+    get size(): number;
+}
+/**
+ * Write one workspace file atomically.
+ *
+ * Order of checks matches the contract: resolve, lock, read the current file
+ * and its fingerprint, CAS, mode, content encoding, size ceiling, parent
+ * directory, then the atomic rename. A `dryRun` stops right after the parent
+ * check and returns the projected node instead of writing.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and the journal.
+ * @param request - Path, content, mode, CAS precondition and dry-run flag.
+ * @param options - Size ceiling, journal sink, tree and timestamp mode.
+ * @returns The new node, previous fingerprint and write metadata.
+ */
+export declare const writeFile: (sandbox: PathSandbox, sessionId: string, request: WriteRequest, options?: WriteOptions) => Promise<WriteResult>;
+/**
+ * Request for {@link useByte}. The target must already exist; `content`
+ * replaces the half-open raw byte range `[startByte, endByte)`.
+ */
+export interface BytePatchRequest {
+    readonly path: string;
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly content: Uint8Array;
+    readonly expectFingerprint: string;
+    readonly expectRangeFingerprint?: string;
+    readonly dryRun?: boolean;
+}
+/**
+ * Request for {@link useLine}. Lines are 1-based and inclusive; `endLine =
+ * startLine - 1` inserts before `startLine`. `content` is encoded with the
+ * file's own charset, so a UTF-16 or Latin-1 file keeps its encoding.
+ */
+export interface LinePatchRequest {
+    readonly path: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly content: string;
+    readonly expectFingerprint: string;
+    readonly expectRangeFingerprint?: string;
+    readonly dryRun?: boolean;
+}
+/**
+ * Journal record for one range patch. It extends the base write record with the
+ * patched span and both range fingerprints, without changing `types.ts`.
+ */
+export interface PatchJournalEntry extends WriteJournalEntry {
+    readonly kind: "line" | "byte";
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly startLine?: number;
+    readonly endLine?: number;
+    readonly previousRangeFingerprint: string;
+    readonly nextRangeFingerprint: string;
+    readonly nextStartByte: number;
+    readonly nextEndByte: number;
+    readonly previousTotalBytes: bigint;
+    readonly nextTotalBytes: bigint;
+}
+/**
+ * Options for {@link useByte} and {@link useLine}. `maxBytes` caps the resulting
+ * file; line patches additionally require the current file to fit that budget
+ * because the text has to be decoded.
+ */
+export interface WritePatchOptions extends WriteOptions {
+    readonly patchJournal?: (entry: PatchJournalEntry) => void;
+}
+/**
+ * Result of a range patch. `bytesWritten` is the final file size, matching
+ * {@link WriteResult}; `previousRangeFingerprint` describes the replaced span
+ * before the write and `nextRangeFingerprint` the inserted span afterwards.
+ */
+export interface WritePatchResult extends WriteResult {
+    readonly kind: "line" | "byte";
+    readonly startByte: number;
+    readonly endByte: number;
+    readonly startLine?: number;
+    readonly endLine?: number;
+    readonly previousRangeFingerprint: string;
+    readonly nextRangeFingerprint: string;
+    readonly nextStartByte: number;
+    readonly nextEndByte: number;
+    readonly previousTotalBytes: bigint;
+    readonly nextTotalBytes: bigint;
+}
+/**
+ * Replace a raw byte range of an existing file.
+ *
+ * The whole-file `expectFingerprint` is mandatory and is verified from the bytes
+ * read under the lock; `expectRangeFingerprint` is a secondary check. The new
+ * file is assembled in memory, written through a same-directory temporary file,
+ * `fsync`ed and renamed, so a reader never observes a partial file.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and journal.
+ * @param request - Path, half-open byte range, replacement bytes and CAS guards.
+ * @param options - Size ceiling, journal sinks, tree and timestamp mode.
+ * @returns Patch result with both fingerprint pairs and the new node.
+ */
+export declare const useByte: (sandbox: PathSandbox, sessionId: string, request: BytePatchRequest, options?: WritePatchOptions) => Promise<WritePatchResult>;
+/**
+ * Replace a line range of an existing text file.
+ *
+ * Line numbers are 1-based and inclusive. The replaced span starts at the first
+ * character of `startLine` and includes the terminator of `endLine` when one
+ * exists, which means `content` is inserted verbatim: include the desired
+ * newline when more lines follow. Use `endLine = startLine - 1` to insert.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and journal.
+ * @param request - Path, inclusive line range, replacement text and CAS guards.
+ * @param options - Size ceiling, journal sinks, tree and timestamp mode.
+ * @returns Patch result with both fingerprint pairs and the new node.
+ */
+export declare const useLine: (sandbox: PathSandbox, sessionId: string, request: LinePatchRequest, options?: WritePatchOptions) => Promise<WritePatchResult>;
+/**
+ * Create a directory inside a root. `create` requires the parent to exist and
+ * fails when the target is already present; `ensure` creates the whole chain
+ * and treats an existing directory as success. The root itself is always a
+ * valid target for `ensure` and never for `create`.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param path - Root-relative POSIX directory path.
+ * @param mode - `create` or `ensure`; defaults to `ensure`.
+ * @returns The resolved path of the directory.
+ */
+export declare const ensureDirectory: (sandbox: PathSandbox, path: string, mode?: "create" | "ensure") => RootedPath;