@nhtio/adk 0.1.0-master-e6c58205 → 0.1.0-master-89b47bec

package/batteries/media/steps/patch.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The structured apply_patch envelope: parser and applier for the
+ * `*** Begin Patch` multi-file dialect.
+ *
+ * @remarks
+ * Internal sibling of the `@nhtio/adk/batteries/media` entry. This dialect derives from the
+ * GitHub Copilot apply_patch format — one of the most robust and battle-tested patch formats
+ * in production use, which is also why models already know how to write it. The grammar
+ * (`*** Begin Patch` … `*** End Patch`, `*** Add File:` / `*** Delete File:` /
+ * `*** Update File:` (+ `*** Move to:`), `@@` context hunks with `+`/`-`/space lines) is
+ * preserved exactly — inventing a "better" variation would forfeit the pretraining. Ported
+ * from the source server's `doc.apply_patch` adapter (its green e2e suite informs the spec
+ * coverage); the context matcher rejects ambiguity (a hunk whose context matches more than
+ * one location fails rather than guessing).
+ */
+/** One parsed `@@` hunk: the context+removal lines and their replacement. */
+export interface ParsedHunk {
+    oldLines: string[];
+    newLines: string[];
+    added: number;
+    removed: number;
+}
+/** `*** Add File:` — create a new file from `+` lines. */
+export interface AddOperation {
+    type: 'add';
+    path: string;
+    content: string;
+    added: number;
+}
+/** `*** Delete File:` — remove a file. */
+export interface DeleteOperation {
+    type: 'delete';
+    path: string;
+}
+/** `*** Update File:` (+ optional `*** Move to:`) — apply hunks, optionally rename. */
+export interface UpdateOperation {
+    type: 'update';
+    path: string;
+    movePath?: string;
+    hunks: ParsedHunk[];
+    added: number;
+    removed: number;
+}
+/** Any one operation of a structured patch. */
+export type PatchOperation = AddOperation | DeleteOperation | UpdateOperation;
+/** The parsed envelope: ordered operations plus totals. */
+export interface ParsedApplyPatch {
+    operations: PatchOperation[];
+    added: number;
+    removed: number;
+}
+/** `true` when `patch` is the structured envelope rather than a unified diff. */
+export declare const isStructuredPatch: (patch: string) => boolean;
+/** Normalize a workspace path: relative, no `.`/`..`/empty segments, forward slashes. */
+export declare const normalizeWorkspacePath: (path: string) => string;
+/**
+ * Parse a structured `*** Begin Patch` envelope.
+ *
+ * @param patch - The raw patch text.
+ * @returns The parsed operations.
+ */
+export declare const parseStructuredPatch: (patch: string) => ParsedApplyPatch;
+/**
+ * Apply an update operation's hunks to `inputText`. Context matching is exact and rejects
+ * ambiguity: a hunk whose old-lines match more than one location past the cursor fails
+ * rather than guessing.
+ *
+ * @param inputText - The file's current text.
+ * @param hunks - The parsed hunks, in order.
+ * @returns The patched text.
+ */
+export declare const applyUpdateHunks: (inputText: string, hunks: ParsedHunk[]) => string;
+/** One file in the virtual workspace a structured patch operates over. */
+export interface WorkspaceFile {
+    text: string;
+    mimeType: string;
+}
+/**
+ * Apply a parsed structured patch to a virtual workspace of files keyed by normalized path.
+ *
+ * @param files - The workspace (mutated in place).
+ * @param patch - The parsed envelope.
+ * @returns The workspace and the number of files touched.
+ */
+export declare const applyOperations: (files: Map<string, WorkspaceFile>, patch: ParsedApplyPatch) => {
+    files: Map<string, WorkspaceFile>;
+    modifiedFiles: number;
+};
+/** Infer a text MIME from a workspace path's extension (Add File outputs). */
+export declare const inferTextMimeFromPath: (path: string) => string;

package/batteries/media/steps/sheet.d.ts

@@ -1,12 +1,16 @@
 /**
- * `sheet.*` step implementations: ExcelJS workbook mutations on in-memory bytes.
+ * `sheet.*` step implementations: thin dispatchers into the engine registry's edit
+ * capability.
  *
  * @remarks
- * Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
- * sheet adapters (its green e2e suite informs the spec coverage). All ten mutations operate on
- * xlsx natively via ExcelJS (optional peer, lazily imported); ODS and legacy-xls inputs are
- * normalized to xlsx first through the configured `sheetNormalize` engine, degrading to a
- * readable failure when none is configured. Output is always xlsx.
+ * Internal sibling of the `@nhtio/adk/batteries/media` entry. The actual workbook surgery
+ * lives in edit-capable engines (`engines/exceljs` preserves styling; `engines/sheetjs`
+ * covers the wider read matrix but strips styling — SheetJS CE limitation). Each step here:
+ * normalizes non-xlsx spreadsheet inputs to xlsx when the selected edit coverage requires it
+ * (any spreadsheet-family MIME with a declared `hasConvert(mime, 'xlsx')` edge qualifies —
+ * ODS/XLS via soffice or sheetjs, XLSB/FODS/SYLK/DIF/DBF/NUMBERS via sheetjs), dispatches the
+ * op through `ctx.engines.edit`, and degrades to a model-actionable failure when no edit
+ * engine is configured.
  */
 import type { StepImpl } from "../runtime";
 /** `sheet.add_rows` — insert rows before/after an index, or append. */

package/batteries/media/steps/text.d.ts

@@ -39,5 +39,8 @@ export declare const redactStep: StepImpl;
 export declare const updateTextStep: StepImpl;
 /** `diff` — compare against another media (text-comparable formats in Phase 0). */
 export declare const diffStep: StepImpl;
-/** `apply_patch` — apply a unified diff to the media text. */
+/**
+ * `apply_patch` — apply a unified diff, or a structured `*** Begin Patch` envelope
+ * (multi-file Add/Delete/Update/Move — the GitHub Copilot apply_patch dialect).
+ */
 export declare const applyPatchStep: StepImpl;

package/batteries/media/validate.d.ts

@@ -21,6 +21,11 @@ export interface CapabilityProbe {
     hasConvert(from?: string, to?: string): boolean;
     /** `true` when some engine declares a mutate capability. */
     hasMutate(): boolean;
+    /**
+     * `true` when some engine declares a matching edit capability (omit both for "any").
+     * Optional so existing probe stubs stay valid; absent means "no edit engines".
+     */
+    hasEdit?(mime?: string, op?: string): boolean;
 }
 /** Options for {@link validateSegments} / {@link validateOps}. */
 export interface ValidateOptions {

package/batteries/media/verbs.d.ts

@@ -45,6 +45,9 @@ export type VerbRequirement = {
     to?: string;
 } | {
     capability: 'mutate';
+} | {
+    capability: 'edit';
+    op?: string;
 };
 /** Broad input families used for verb-applicability checks. */
 export type FormatFamily = 'document' | 'spreadsheet' | 'presentation' | 'image' | 'audio' | 'any';
@@ -69,7 +72,7 @@ export interface VerbSpec {
     /** Output kind. May be refined by an `out`-style arg (documented per verb). */
     output: VerbOutput;
 }
-/** Conversion targets supported by `convert` (matches the server's enum exactly). */
+/** Conversion targets supported by `convert` (the server's enum plus the SheetJS/data matrix). */
 export declare const CONVERT_TARGETS: readonly [
     "pdf",
     "html",
@@ -77,6 +80,7 @@ export declare const CONVERT_TARGETS: readonly [
     "md",
     "csv",
     "json",
+    "yaml",
     "docx",
     "doc",
     "rtf",
@@ -84,6 +88,13 @@ export declare const CONVERT_TARGETS: readonly [
     "xlsx",
     "xls",
     "ods",
+    "xlsm",
+    "xlsb",
+    "fods",
+    "sylk",
+    "dif",
+    "dbf",
+    "numbers",
     "pptx",
     "ppt",
     "odp"