@sidub-inc/docuoria.cli 1.0.15

package/payload/skill/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/skill/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/skill/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/skill/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/skill/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/skill/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/skill/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/skill/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/skill/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);
+}