@sidub-inc/docuoria.cli 1.0.15

package/payload/scripts/execute.csx

@@ -0,0 +1,89 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-06 — Wrapper over IDocuoriaEngine.ExecuteTemplateAsync<TGenerator, TOptions>.
+// Args: --pdf <path> --template <file.json> --format csv|json [--output <path>]
+// Success: SucceededResult → write payload bytes (to --output or wrap as string in stdout JSON).
+// Rejected/Failed: emit { status, result } and exit 1.
+
+using System.Text;
+using Docuoria.Configuration;
+using Docuoria.Contracts;
+using Docuoria.Models;
+using Docuoria.Output.Csv;
+using Docuoria.Output.Json;
+using Docuoria.Results;
+
+try
+{
+    Cli.Help(Args, "execute.csx", "Full pipeline run with output generation (CSV or JSON)",
+        ("pdf", true, "Path to the source PDF", false),
+        ("template", true, "Path to the template JSON file", false),
+        ("format", true, "Output format: csv or json", false),
+        ("output", false, "Write output to this file path (default: stdout)", false));
+
+    var pdfPath = Cli.Require(Args, "pdf");
+    var templatePath = Cli.Require(Args, "template");
+    var format = Cli.Require(Args, "format").Trim().ToLowerInvariant();
+    var outputPath = Cli.Get(Args, "output");
+
+    if (format != "csv" && format != "json")
+    {
+        JsonOut.Error("bad-format", "expected csv|json", null, 2);
+    }
+    if (!File.Exists(templatePath))
+    {
+        JsonOut.Error("template-not-found", $"Template not found at '{templatePath}'", null, 1);
+    }
+
+    var template = Template.FromJson(File.ReadAllText(templatePath));
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: false);
+    var engine = ScriptHost.GetEngine(host);
+
+    using var pdf = LoadPdf(pdfPath);
+
+    ProcessingResult result = format switch
+    {
+        "csv" => await engine.ExecuteTemplateAsync<CsvOutputGenerator, CsvGeneratorOptions>(
+            pdf, template, new CsvGeneratorOptions()),
+        "json" => await engine.ExecuteTemplateAsync<JsonOutputGenerator, JsonGeneratorOptions>(
+            pdf, template, new JsonGeneratorOptions()),
+        _ => throw new InvalidOperationException("unreachable")
+    };
+
+    switch (result)
+    {
+        case SucceededResult ok:
+            var payload = ok.Output.Payload;
+            if (!string.IsNullOrEmpty(outputPath))
+            {
+                Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(outputPath!))!);
+                await File.WriteAllBytesAsync(outputPath!, payload.ToArray());
+                JsonOut.Write(new { status = "ok", path = outputPath });
+            }
+            else
+            {
+                var text = Encoding.UTF8.GetString(payload.Span);
+                JsonOut.Write(new { status = "ok", format, output = text });
+            }
+            break;
+
+        case RejectedResult rej:
+            JsonOut.Error("rejected", $"Rejected ({rej.Reason}){(rej.Detail is not null ? $": {rej.Detail}" : "")}", null, 1);
+            break;
+
+        case FailedResult fail:
+            JsonOut.Error("failed", fail.ErrorMessage, fail.InnerDetail, 1);
+            break;
+
+        default:
+            JsonOut.Error("unknown-result", result.GetType().Name, null, 1);
+            break;
+    }
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/inspect.csx

@@ -0,0 +1,43 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-01 — Agent-facing wrapper over IDocuoriaEngine.InspectAsync (read-only PDF probe).
+// Args: --pdf <path> [--page <n>]
+// stdout: PdfInspection JSON
+// Exit codes: 0 success, 1 handled error, 2 bad args.
+
+using Docuoria.Configuration;
+using Docuoria.Contracts;
+using Docuoria.Models;
+
+try
+{
+    Cli.Help(Args, "inspect.csx", "Inspect PDF structure (page count, text blocks, tables)",
+        ("pdf", true, "Path to the source PDF", false),
+        ("page", false, "1-based page index (default: all pages)", false));
+
+    var pdfPath = Cli.Require(Args, "pdf");
+    var pageStr = Cli.Get(Args, "page");
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: false);
+    var engine = ScriptHost.GetEngine(host);
+
+    PageFilter? filter = null;
+    if (!string.IsNullOrWhiteSpace(pageStr))
+    {
+        if (!int.TryParse(pageStr, out var page) || page < 1)
+        {
+            JsonOut.Error("bad-arg", "--page must be a positive integer", null, 2);
+        }
+        filter = PageFilter.SinglePage(page);
+    }
+
+    using var pdf = LoadPdf(pdfPath);
+    var result = await engine.InspectAsync(pdf, filter);
+    JsonOut.Write(result);
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/list-templates.csx

@@ -0,0 +1,34 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-08 — enumerate ITemplateStoreProvider.ListAsync.
+// stdout: { templates: [..ids..] }
+
+using Docuoria.Storage;
+
+try
+{
+    Cli.Help(Args, "list-templates.csx", "List all template IDs in the configured store",
+        ("store-path", false, "Local template store directory (default: ./templates)", false),
+        ("store-url", false, "API template store URL (mutually exclusive with --store-path)", false),
+        ("store-key", false, "Function key for API store authentication", false));
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: true);
+    var store = ScriptHost.GetStore(host);
+    if (store is null)
+    {
+        JsonOut.Error("no-store", "ITemplateStoreProvider is not registered. Pass --store-path <dir> to specify a local template store directory.", null, 1);
+    }
+
+    var ids = new List<string>();
+    await foreach (var id in store!.ListAsync())
+    {
+        ids.Add(id);
+    }
+    JsonOut.Write(new { templates = ids });
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/load-template.csx

@@ -0,0 +1,54 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-09 — fetch a template by ID and emit its JSON.
+// Args: --id <identifier> [--output <path>]
+// stdout: parsed template JSON or { status, path }.
+
+using System.Text.Json;
+using Docuoria.Serialization;
+using Docuoria.Storage;
+
+try
+{
+    Cli.Help(Args, "load-template.csx", "Fetch a template by ID and emit its JSON",
+        ("id", true, "Template identifier", false),
+        ("output", false, "Write template JSON to this file path", false),
+        ("store-path", false, "Local template store directory (default: ./templates)", false),
+        ("store-url", false, "API template store URL (mutually exclusive with --store-path)", false),
+        ("store-key", false, "Function key for API store authentication", false));
+
+    var id = Cli.Require(Args, "id");
+    var outputPath = Cli.Get(Args, "output");
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: true);
+    var store = ScriptHost.GetStore(host);
+    if (store is null)
+    {
+        JsonOut.Error("no-store", "ITemplateStoreProvider is not registered. Pass --store-path <dir> to specify a local template store directory.", null, 1);
+    }
+
+    var tpl = await store!.LoadAsync(id);
+    if (tpl is null)
+    {
+        JsonOut.Error("not-found", $"Template '{id}' not found. Run list-templates.csx to see available template IDs.", null, 1);
+    }
+
+    var json = tpl!.ToJson();
+    if (!string.IsNullOrEmpty(outputPath))
+    {
+        Directory.CreateDirectory(Path.GetDirectoryName(Path.GetFullPath(outputPath!))!);
+        await File.WriteAllTextAsync(outputPath!, json);
+        JsonOut.Write(new { status = "ok", path = outputPath });
+    }
+    else
+    {
+        var element = JsonSerializer.Deserialize<JsonElement>(json, DocuoriaJsonOptions.Default);
+        JsonOut.Write(element);
+    }
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/save-template.csx

@@ -0,0 +1,53 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-10 — persist a template JSON file to the configured store.
+// Args: --template <path> [--overwrite] [--store-path <dir>] [--store-url <url>] [--store-key <key>]
+// stdout: { status, identifier }.
+
+using Docuoria.Models;
+using Docuoria.Storage;
+using Docuoria.Storage.Exceptions;
+
+try
+{
+    Cli.Help(Args, "save-template.csx", "Persist a template JSON file to the configured store",
+        ("template", true, "Path to the template JSON file", false),
+        ("overwrite", false, "Overwrite if template already exists", true),
+        ("store-path", false, "Local template store directory (default: ./templates)", false),
+        ("store-url", false, "API template store URL (mutually exclusive with --store-path)", false),
+        ("store-key", false, "Function key for API store authentication", false));
+
+    var filePath = Cli.Require(Args, "template");
+    var overwrite = Cli.Has(Args, "overwrite");
+
+    if (!File.Exists(filePath))
+    {
+        JsonOut.Error("template-not-found", $"Template file not found at '{filePath}'", null, 1);
+    }
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: true);
+    var store = ScriptHost.GetStore(host);
+    if (store is null)
+    {
+        JsonOut.Error("no-store", "ITemplateStoreProvider is not registered. Pass --store-path <dir> to specify a local template store directory.", null, 1);
+    }
+
+    var tpl = Template.FromJson(File.ReadAllText(filePath));
+
+    try
+    {
+        await store!.SaveAsync(tpl, overwrite);
+    }
+    catch (TemplateAlreadyExistsException tae)
+    {
+        JsonOut.Error("already-exists", $"{tae.Message} Use --overwrite to replace the existing template.", null, 1);
+    }
+
+    JsonOut.Write(new { status = "ok", identifier = tpl.Identifier });
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/schema-info.csx

@@ -0,0 +1,84 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-12 — Dump all type/enum/mode information for the SDK.
+// Args: (none)
+// stdout: JSON object with fieldTypes, extractionSources, modes, matchRules, subFieldMappings.
+
+using System.Reflection;
+using Docuoria.Models;
+
+try
+{
+    Cli.Help(Args, "schema-info.csx", "List all SDK types, enums, modes, and valid values");
+
+    var fieldTypes = new Dictionary<int, string>();
+    foreach (var val in Enum.GetValues<FieldType>())
+    {
+        fieldTypes[(int)val] = val.ToString();
+    }
+
+    var extractionSources = new[]
+    {
+        "TextPatternExtractionSource",
+        "TextAnchorExtractionSource",
+        "TableCellExtractionSource",
+        "TableRowsExtractionSource",
+        "MetadataFieldExtractionSource",
+        "FallbackExtractionSource"
+    };
+
+    var modes = new Dictionary<string, object>
+    {
+        ["TextPatternExtractionSource"] = new { mode = new[] { "Token", "Pattern", "AllMatches" }, notes = new { Token = "requires 'literalToken'", Pattern = "requires 'regexPattern'", AllMatches = "requires 'regexPattern'" } },
+        ["TableRowsExtractionSource"] = new { mode = new[] { "ByHeader", "Ordinal" } },
+        ["TextPatternMatchRule"] = new { mode = new[] { "AnyToken", "AllTokens" } },
+        ["FileNameMatchRule"] = new { mode = new[] { "Glob", "Regex" } },
+        ["CompositeMatchRule"] = new { @operator = new[] { "And", "Or", "Not" } }
+    };
+
+    var matchRules = new[]
+    {
+        "TextPatternMatchRule",
+        "FileNameMatchRule",
+        "TextAnchorMatchRule",
+        "MetadataMatchRule",
+        "PageGeometryMatchRule",
+        "TableMatchRule",
+        "CompositeMatchRule"
+    };
+
+    var subFieldMappings = new[]
+    {
+        "NamedGroupSubFieldMapping",
+        "RegexGroupSubFieldMapping",
+        "HeaderSubFieldMapping",
+        "OrdinalSubFieldMapping"
+    };
+
+    var metadataFields = new[]
+    {
+        "Title", "Author", "Subject", "Keywords",
+        "Creator", "Producer", "CreationDate", "ModifiedDate"
+    };
+
+    JsonOut.Write(new
+    {
+        fieldTypes,
+        extractionSources,
+        modes,
+        matchRules,
+        subFieldMappings,
+        metadataFields,
+        notes = new
+        {
+            fieldType = "fieldType serializes as INTEGER (0-5), not string. Use the integer value in template JSON.",
+            kind = "All polymorphic types use '$kind' discriminator with the CLR class name."
+        }
+    });
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/test-groups.csx

@@ -0,0 +1,44 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-03 — Wrapper over IDocuoriaEngine.TestGroupsAsync.
+// Args: --pattern <regex> --pdf <path> [--page <n>]
+// stdout: PatternGroupTestResult JSON.
+
+using Docuoria.Configuration;
+using Docuoria.Contracts;
+using Docuoria.Models;
+
+try
+{
+    Cli.Help(Args, "test-groups.csx", "Test each capture group of a regex independently",
+        ("pdf", true, "Path to the source PDF", false),
+        ("pattern", true, "Multi-group regex pattern", false),
+        ("page", false, "1-based page index (default: all pages)", false));
+
+    var pattern = Cli.Require(Args, "pattern");
+    var pdfPath = Cli.Require(Args, "pdf");
+    var pageStr = Cli.Get(Args, "page");
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: false);
+    var engine = ScriptHost.GetEngine(host);
+
+    PatternTestOptions? options = null;
+    if (!string.IsNullOrWhiteSpace(pageStr))
+    {
+        if (!int.TryParse(pageStr, out var page) || page < 1)
+        {
+            JsonOut.Error("bad-arg", "--page must be a positive integer", null, 2);
+        }
+        options = new PatternTestOptions { PageFilter = PageFilter.SinglePage(page) };
+    }
+
+    using var pdf = LoadPdf(pdfPath);
+    var result = await engine.TestGroupsAsync(pdf, pattern, options);
+    JsonOut.Write(result);
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/test-pattern.csx

@@ -0,0 +1,61 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-02 — Wrapper over IDocuoriaEngine.TestPatternAsync.
+// Args: --pattern <regex> --pdf <path> [--page <n>] [--block-separator <str>]
+// stdout: PatternTestResult JSON (Error round-trips per Phase 24 — do NOT swallow).
+
+using Docuoria.Configuration;
+using Docuoria.Contracts;
+using Docuoria.Models;
+
+try
+{
+    Cli.Help(Args, "test-pattern.csx", "Test a regex pattern against PDF text",
+        ("pdf", true, "Path to the source PDF", false),
+        ("pattern", true, "Regex pattern to test", false),
+        ("page", false, "1-based page index (default: all pages)", false),
+        ("block-separator", false, "Override block separator for text flattening", false));
+
+    var pattern = Cli.Require(Args, "pattern");
+    var pdfPath = Cli.Require(Args, "pdf");
+    var blockSep = Cli.Get(Args, "block-separator");
+    var pageStr = Cli.Get(Args, "page");
+
+    using var host = ScriptHost.CreateHost(Args.ToArray(), includeStore: false);
+    var engine = ScriptHost.GetEngine(host);
+
+    PatternTestOptions? options = null;
+
+    // Build options from optional flags
+    string? blockSepValue = blockSep;
+    PageFilter? pageFilter = null;
+
+    if (!string.IsNullOrWhiteSpace(pageStr))
+    {
+        if (!int.TryParse(pageStr, out var page) || page < 1)
+        {
+            JsonOut.Error("bad-arg", "--page must be a positive integer", null, 2);
+        }
+        pageFilter = PageFilter.SinglePage(page);
+    }
+
+    if (!string.IsNullOrEmpty(blockSepValue) || pageFilter is not null)
+    {
+        options = new PatternTestOptions
+        {
+            BlockSeparator = blockSepValue ?? "\n",
+            PageFilter = pageFilter
+        };
+    }
+
+    using var pdf = LoadPdf(pdfPath);
+
+    var result = await engine.TestPatternAsync(pdf, pattern, options);
+    JsonOut.Write(result);
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/scripts/validate-template.csx

@@ -0,0 +1,54 @@
+#load "_common.csx"
+
+#nullable enable
+
+// SCR-04 — Template.FromJson + Validate() static check (no engine required, but we host for consistency).
+// Args: --template <file.json>
+// stdout: { valid, errors }
+
+using System.Text.Json;
+using Docuoria.Models;
+
+try
+{
+    Cli.Help(Args, "validate-template.csx", "Validate a template JSON file against the schema",
+        ("template", true, "Path to the template JSON file", false));
+
+    var templatePath = Cli.Require(Args, "template");
+    if (!File.Exists(templatePath))
+    {
+        JsonOut.Error("template-not-found", $"Template not found at '{templatePath}'", null, 1);
+    }
+
+    var json = File.ReadAllText(templatePath);
+
+    Template tpl;
+    try
+    {
+        tpl = Template.FromJson(json);
+    }
+    catch (JsonException jex)
+    {
+        var message = jex.Message;
+        var hint = (string?)null;
+
+        // Detect fieldType string-vs-integer errors and add a helpful hint.
+        if (message.Contains("FieldType", StringComparison.OrdinalIgnoreCase)
+            || (message.Contains("fieldType", StringComparison.OrdinalIgnoreCase))
+            || (message.Contains("could not be converted") && message.Contains("String", StringComparison.Ordinal)))
+        {
+            hint = "fieldType must be an integer (0=String, 1=Number, 2=Integer, 3=Boolean, 4=Date, 5=Timestamp). "
+                 + "Do NOT use string values like \"String\" or \"Number\".";
+        }
+
+        JsonOut.Error("parse-error", hint is not null ? $"{message} — Hint: {hint}" : message, null, 1);
+        return;
+    }
+
+    var errors = tpl.Validate();
+    JsonOut.Write(new { valid = errors.Count == 0, errors });
+}
+catch (Exception ex)
+{
+    JsonOut.Error("unhandled", ex.Message, ex.ToString(), 1);
+}

package/payload/skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: docuoria
+description: Use this skill when working with Docuoria to extract structured data from PDFs, author or validate a template, design match rules for classification, diagnose a FailedResult or RejectedResult, select an ExtractionSource type, write or debug a regex pattern, or verify that PDF processing is local and private. Apply even when the user does not say "Docuoria" — any task involving the Docuoria CLI scripts, template JSON, or the IDocuoriaEngine API qualifies.
+license: MIT
+compatibility: Requires .NET 10 SDK and the `dotnet-script` global tool. SDK assembly (`Docuoria.dll`) is bundled under `assets/lib/`; transitive NuGet dependencies (PdfPig, Tabula, CsvHelper, pythonnet, Microsoft.Extensions.*) are resolved by `dotnet-script` at first run.
+---
+
+# Docuoria Skill
+
+## Installing this skill
+
+This skill directory was scaffolded by the Docuoria CLI. To install or update:
+
+```bash
+# npm (Node.js ≥ 20)
+npm install -g @sidub/docuoria
+docuoria init
+
+# .NET global tool
+dotnet tool install -g Docuoria.Cli
+docuoria init
+
+# Update an existing installation
+docuoria update
+
+# Check status / drift
+docuoria list-tools
+docuoria doctor
+```
+
+See `docs/cli.md` in the Docuoria repository for the full command reference.
+
+---
+
+## Invocation
+
+All scripts follow `dotnet script scripts/<name>.csx -- --<flag> <value>`, run from the skill root. The `--` separator is mandatory — without it, dotnet-script consumes the flags as its own. Positional arguments are rejected; pass `--help` to any script for its full flag list.
+
+Scripts divide into two groups:
+
+| Group | Scripts | Store flag |
+| --- | --- | --- |
+| **Store-aware** — read from or write to a template store | `classify`, `evaluate-match`, `list-templates`, `load-template`, `save-template` | `--store-path <dir>` or `--store-url <url>` |
+| **Standalone** — operate on individual PDF and/or template files | `inspect`, `test-pattern`, `test-groups`, `dry-run`, `execute`, `validate-template` | — |
+
+Store-aware scripts accept `--store-path <dir>` (local directory) or `--store-url <url>` (API endpoint) to locate templates; these flags are mutually exclusive. When omitted, `--store-path` defaults to `./templates` relative to the process working directory — since the CWD varies by environment, always pass the store location explicitly.
+
+## Workflow
+
+The pipeline runs in order; classification determines the entry point. Load `references/workflow.md` for the full step-by-step guide.
+
+1. **Classify** — match the PDF against all stored templates
+2. **Inspect** — read the engine's text extraction (when no template matches)
+3. **Test** — prove regex patterns against the engine's haystack
+4. **Build** — author the template JSON, validate classification rules and schema
+5. **Dry-run** — end-to-end extraction without output generation
+6. **Execute** — full pipeline producing CSV or JSON output
+7. **Store** — persist the template and verify it ranks correctly
+
+## Routing
+
+Consult the canonical reference before relying on memory. Each concern has a single owner.
+
+| If the agent needs to… | Load |
+| --- | --- |
+| Follow the full pipeline step-by-step | `references/workflow.md` |
+| Pick an `ExtractionSource` subtype for a field (`TextPattern`, `TableRows`, `TextAnchor`, `MetadataField`, `Fallback`) | `references/decision-tree.md` |
+| Design a discriminating `rootMatchRule` (token selection, composite architecture, structural rules, weights, thresholds) | `references/classification.md` |
+| Diagnose a `RejectedResult`, `FailedResult`, classification failure, or empty/incomplete `DryRunSucceeded` | `references/failure-tree.md` |
+| Map a stderr `error.code` to a remediation branch | `references/failure-tree.md` § Stderr error.code → Branch routing |
+| Copy a regex pattern from the library or adapt one to a specific PDF | `references/patterns.md` then `references/pattern-authoring.md` |
+| Look up a CLI script's flags, output envelope, or error codes | `references/scripts.md` |
+| Look up a template JSON property, `$kind` discriminator, enum value, or shape | `references/template-reference.md` |
+| Answer whether PDF processing is local/private | `references/privacy.md` |
+
+## Skill layout
+
+- `SKILL.md` — this router; loaded at skill activation.
+- `references/` — deep guides loaded on demand (see Routing table).
+- `scripts/` — `dotnet-script` CLI surface (`_common.csx` plus 11 verb scripts).
+- `assets/lib/Docuoria.dll` — bundled SDK assembly.
+- `assets/schemas/template-schema.json` — JSON Schema for template authoring and validation.
+- `examples/` — three worked end-to-end walkthroughs.
+
+## Gotchas
+
+- **`fieldType` in template JSON must be an integer (0–5), never a string.** The engine rejects string values with `RejectionReason.MalformedTemplate`. Enum: 0 String, 1 Number, 2 Integer, 3 Boolean, 4 Date, 5 Timestamp. Run `validate-template.csx` to catch this before dry-run.
+- **Adapt every regex to the actual PDF.** The engine's flattened text differs from the visual layout — whitespace, line breaks, and character encoding may not match what you see. Validate with `test-pattern.csx` and `inspect.csx` rather than pasting library patterns verbatim.