alran 0.0.0-stage → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (506) hide show
  1. package/ALRAN_TOOLS_NOTICES.md +64 -0
  2. package/LICENSE +27 -0
  3. package/LICENSE-STATUS.md +21 -0
  4. package/NOTICE +6 -0
  5. package/README.md +289 -2
  6. package/THIRD_PARTY_NOTICES.md +113 -0
  7. package/alran-tools.js +3 -0
  8. package/assets/agents/_default/prompt-auto_classifier.md +185 -0
  9. package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
  10. package/assets/agents/_default/prompt-base-all.md +133 -0
  11. package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
  12. package/assets/agents/_default/prompt-base-windows.md +5 -0
  13. package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
  14. package/assets/agents/_default/prompt-base-worker.md +10 -0
  15. package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
  16. package/assets/agents/_default/prompt-compact.md +76 -0
  17. package/assets/agents/_default/prompt-compact_continue.md +9 -0
  18. package/assets/agents/_default/prompt-git.md +8 -0
  19. package/assets/agents/_default/prompt-goal.md +13 -0
  20. package/assets/agents/_default/prompt-session-branch.md +3 -0
  21. package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
  22. package/assets/agents/_default/prompt-session-root.md +3 -0
  23. package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
  24. package/assets/agents/_default/prompt-title.md +11 -0
  25. package/assets/agents/_default/prompt-tool_agent.md +22 -0
  26. package/assets/agents/_migration/README.md +20 -0
  27. package/assets/agents/_migration/coder/PERSONA.md +11 -0
  28. package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
  29. package/assets/agents/_migration/general/PERSONA.md +11 -0
  30. package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
  31. package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
  32. package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
  33. package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
  34. package/assets/agents/_v2/explore.md.hbs +38 -0
  35. package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
  36. package/assets/agents/_v2/verifier.md.hbs +32 -0
  37. package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
  38. package/assets/agents/_v2/worker.md.hbs +27 -0
  39. package/assets/agents/alran/PERSONA.md +7 -0
  40. package/assets/agents/alran/features/cron.md.hbs +0 -0
  41. package/assets/agents/alran/features/delegation.md.hbs +56 -0
  42. package/assets/agents/alran/features/memory.md.hbs +61 -0
  43. package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
  44. package/assets/agents/alran/features/task-management.md.hbs +11 -0
  45. package/assets/agents/alran/features/web-search.md.hbs +11 -0
  46. package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
  47. package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
  48. package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
  49. package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
  50. package/assets/agents/alran/prompt-session-root.md +4 -0
  51. package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
  52. package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
  53. package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
  54. package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
  55. package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
  56. package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
  57. package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
  58. package/assets/agents/alran/system-prompt.md.hbs +97 -0
  59. package/assets/agents/builtin-agents.json +1 -0
  60. package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
  61. package/assets/agents/desktop-task/checkpoint/system.md +19 -0
  62. package/assets/agents/desktop-task/output-revision/system.md +1 -0
  63. package/assets/agents/desktop-task/retry/continuation.md +4 -0
  64. package/assets/agents/desktop-task/session-title/system.md +41 -0
  65. package/assets/agents/explore/PERSONA.md +8 -0
  66. package/assets/agents/explore/agent.md +14 -0
  67. package/assets/agents/explore/system-prompt.md.hbs +35 -0
  68. package/assets/agents/greeting.md +61 -0
  69. package/assets/agents/managed-prompts.json +47 -0
  70. package/assets/agents/prompt-exemptions.json +36 -0
  71. package/assets/agents/verifier/PERSONA.md +8 -0
  72. package/assets/agents/verifier/agent.md +17 -0
  73. package/assets/agents/verifier/system-prompt.md.hbs +28 -0
  74. package/assets/agents/worker/PERSONA.md +8 -0
  75. package/assets/agents/worker/agent.md +18 -0
  76. package/assets/agents/worker/system-prompt.md.hbs +22 -0
  77. package/assets/agents/workflow/code-review/review-candidates.md +120 -0
  78. package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
  79. package/assets/agents/workflow/goal/budget-limit.md +16 -0
  80. package/assets/agents/workflow/goal/continuation.md +62 -0
  81. package/assets/agents/workflow/goal/objective-updated.md +16 -0
  82. package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
  83. package/assets/agents/workflow/goal/recovery.md +11 -0
  84. package/assets/agents/workflow/goal/terminal-audit.md +10 -0
  85. package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
  86. package/assets/agents/workflow/prompt-hook/system.md +0 -0
  87. package/assets/models-dev-catalog.json.gz +0 -0
  88. package/assets/prompts/code-review/review-candidates.md +120 -0
  89. package/assets/prompts/code-review/reviewer-system.md +75 -0
  90. package/assets/skills/alran-tools-master/SKILL.md +127 -0
  91. package/assets/skills/code-review/SKILL.md +51 -0
  92. package/assets/skills/cu-desktop/SKILL.md +255 -0
  93. package/assets/skills/deep-research/SKILL.md +30 -0
  94. package/assets/skills/deploy-website/SKILL.md +52 -0
  95. package/assets/skills/docx/LICENSE +21 -0
  96. package/assets/skills/docx/SKILL.md +259 -0
  97. package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
  98. package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
  99. package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
  100. package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
  101. package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
  102. package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
  103. package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
  104. package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
  105. package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
  106. package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
  107. package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
  108. package/assets/skills/docx/docs/acceptance.md +139 -0
  109. package/assets/skills/docx/docs/anti-patterns.md +14 -0
  110. package/assets/skills/docx/docs/backends.md +116 -0
  111. package/assets/skills/docx/docs/evidence.md +73 -0
  112. package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
  113. package/assets/skills/docx/docs/index.md +50 -0
  114. package/assets/skills/docx/docs/rendered-delivery.md +125 -0
  115. package/assets/skills/docx/docs/router.md +122 -0
  116. package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
  117. package/assets/skills/docx/docs/task-apply-template.md +141 -0
  118. package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
  119. package/assets/skills/docx/docs/task-create.md +124 -0
  120. package/assets/skills/docx/docs/task-edit-fill.md +69 -0
  121. package/assets/skills/docx/docs/task-read-content.md +148 -0
  122. package/assets/skills/docx/docs/task-read-rendered.md +78 -0
  123. package/assets/skills/docx/docs/task-read-structure.md +93 -0
  124. package/assets/skills/docx/docs/task-repair-layout.md +70 -0
  125. package/assets/skills/docx/docs/template-dsl.md +32 -0
  126. package/assets/skills/docx/docs/track-changes.md +15 -0
  127. package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
  128. package/assets/skills/docx/references/cjk_typography.md +357 -0
  129. package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
  130. package/assets/skills/docx/references/comments_guide.md +191 -0
  131. package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
  132. package/assets/skills/docx/references/design_principles.md +819 -0
  133. package/assets/skills/docx/references/openxml_element_order.md +308 -0
  134. package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
  135. package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
  136. package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
  137. package/assets/skills/docx/references/openxml_namespaces.md +82 -0
  138. package/assets/skills/docx/references/openxml_units.md +72 -0
  139. package/assets/skills/docx/references/sample-patch-plans.json +22 -0
  140. package/assets/skills/docx/references/sample-task-intents.json +5 -0
  141. package/assets/skills/docx/references/sample-template-manifests.json +21 -0
  142. package/assets/skills/docx/references/scenario_a_create.md +284 -0
  143. package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
  144. package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
  145. package/assets/skills/docx/references/track_changes_guide.md +200 -0
  146. package/assets/skills/docx/references/troubleshooting.md +506 -0
  147. package/assets/skills/docx/references/typography_guide.md +294 -0
  148. package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
  149. package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
  150. package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
  151. package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
  152. package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
  153. package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
  154. package/assets/skills/docx/scripts/docx_preview.sh +37 -0
  155. package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
  156. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
  157. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
  158. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
  159. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
  160. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
  161. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
  162. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
  163. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
  164. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
  165. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
  166. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
  167. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
  168. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
  169. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
  170. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
  171. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
  172. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
  173. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
  174. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
  175. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
  176. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
  177. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
  178. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
  179. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
  180. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
  181. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
  182. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
  183. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
  184. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
  185. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
  186. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
  187. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
  188. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
  189. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
  190. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
  191. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
  192. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
  193. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
  194. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
  195. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
  196. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
  197. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
  198. package/assets/skills/docx/scripts/env_check.ps1 +327 -0
  199. package/assets/skills/docx/scripts/env_check.sh +340 -0
  200. package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
  201. package/assets/skills/docx/scripts/pack_docx.py +31 -0
  202. package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
  203. package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
  204. package/assets/skills/docx/scripts/rendered_report.py +609 -0
  205. package/assets/skills/docx/scripts/setup.ps1 +542 -0
  206. package/assets/skills/docx/scripts/setup.sh +537 -0
  207. package/assets/skills/docx/scripts/unpack_docx.py +29 -0
  208. package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
  209. package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
  210. package/assets/skills/edit-deployed-website/SKILL.md +27 -0
  211. package/assets/skills/init/SKILL.md +135 -0
  212. package/assets/skills/llm-call/SKILL.md +48 -0
  213. package/assets/skills/llm-call/scripts/llm_call.py +458 -0
  214. package/assets/skills/pdf/SKILL.md +280 -0
  215. package/assets/skills/pdf/docs/advanced-reference.md +711 -0
  216. package/assets/skills/pdf/docs/create-guide.md +437 -0
  217. package/assets/skills/pdf/docs/design-guide.md +204 -0
  218. package/assets/skills/pdf/docs/forms-guide.md +462 -0
  219. package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
  220. package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
  221. package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
  222. package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
  223. package/assets/skills/pdf/docs/read-guide.md +358 -0
  224. package/assets/skills/pdf/docs/reformat-guide.md +238 -0
  225. package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
  226. package/assets/skills/pdf/docs/troubleshooting.md +86 -0
  227. package/assets/skills/pdf/docs/vision-guide.md +188 -0
  228. package/assets/skills/pdf/scripts/__init__.py +0 -0
  229. package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
  230. package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
  231. package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
  232. package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
  233. package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
  234. package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
  235. package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
  236. package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
  237. package/assets/skills/pdf/scripts/make.sh +388 -0
  238. package/assets/skills/pdf/scripts/merge.py +112 -0
  239. package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
  240. package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
  241. package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
  242. package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
  243. package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
  244. package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
  245. package/assets/skills/pdf/scripts/render/__init__.py +0 -0
  246. package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
  247. package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
  248. package/assets/skills/pdf/scripts/render_html.cjs +205 -0
  249. package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
  250. package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
  251. package/assets/skills/pdf/templates/INDEX.md +90 -0
  252. package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
  253. package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
  254. package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
  255. package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
  256. package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
  257. package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
  258. package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
  259. package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
  260. package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
  261. package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
  262. package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
  263. package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
  264. package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
  265. package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
  266. package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
  267. package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
  268. package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
  269. package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
  270. package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
  271. package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
  272. package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
  273. package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
  274. package/assets/skills/pptx/SKILL.md +283 -0
  275. package/assets/skills/pptx/references/design-system.md +424 -0
  276. package/assets/skills/pptx/references/editing.md +162 -0
  277. package/assets/skills/pptx/references/element-map.md +229 -0
  278. package/assets/skills/pptx/references/pitfalls.md +205 -0
  279. package/assets/skills/pptx/references/pptxgenjs.md +420 -0
  280. package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
  281. package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
  282. package/assets/skills/pptx/references/slide-types.md +413 -0
  283. package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
  284. package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
  285. package/assets/skills/pptx/scripts/extract_comments.py +468 -0
  286. package/assets/skills/pptx/scripts/extract_images.py +226 -0
  287. package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
  288. package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
  289. package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
  290. package/assets/skills/resume-codex/SKILL.md +53 -0
  291. package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
  292. package/assets/skills/skill-creator/SKILL.md +188 -0
  293. package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
  294. package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
  295. package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
  296. package/assets/skills/skill-creator/references/description-rubric.md +83 -0
  297. package/assets/skills/skill-creator/references/skill-template.md +101 -0
  298. package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
  299. package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
  300. package/assets/skills/skill-refiner/SKILL.md +137 -0
  301. package/assets/skills/visual-page/SKILL.md +194 -0
  302. package/assets/skills/x-link-reader/SKILL.md +108 -0
  303. package/assets/skills/xlsx/SKILL.md +498 -0
  304. package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
  305. package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
  306. package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
  307. package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
  308. package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
  309. package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
  310. package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
  311. package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
  312. package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
  313. package/assets/skills/xlsx/scripts/office/pack.py +159 -0
  314. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  315. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  316. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  317. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  318. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  319. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  320. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  321. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  322. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  323. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  324. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  325. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  326. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  327. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  328. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  329. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  330. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  331. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  332. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  333. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  334. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  335. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  336. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  337. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  338. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  339. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  340. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  341. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  342. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  343. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  344. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  345. package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
  346. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
  347. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
  348. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
  349. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
  350. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
  351. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  352. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
  353. package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
  354. package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
  355. package/assets/skills/xlsx/scripts/office/validate.py +117 -0
  356. package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
  357. package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
  358. package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
  359. package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
  360. package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
  361. package/assets/skills/xlsx/scripts/recalc.py +450 -0
  362. package/chunks/account-commands-JZ6NXTTK.js +2 -0
  363. package/chunks/anthropic-MN33DP4E.js +2 -0
  364. package/chunks/application-ITGAJ4HC.js +2 -0
  365. package/chunks/auth-command-V3RVPLZO.js +2 -0
  366. package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
  367. package/chunks/chunk-2TF6JAQM.js +2 -0
  368. package/chunks/chunk-33CNY6GP.js +2 -0
  369. package/chunks/chunk-3AODGLMF.js +2 -0
  370. package/chunks/chunk-44VPC5LA.js +38 -0
  371. package/chunks/chunk-4CN3IJFH.js +2 -0
  372. package/chunks/chunk-4PDIO3M6.js +2 -0
  373. package/chunks/chunk-4X22UJQH.js +164 -0
  374. package/chunks/chunk-6255CZPL.js +2 -0
  375. package/chunks/chunk-6P4UKHGR.js +2 -0
  376. package/chunks/chunk-7QLAXRD2.js +1085 -0
  377. package/chunks/chunk-7XYOYZX2.js +2 -0
  378. package/chunks/chunk-A7GMJNA2.js +29 -0
  379. package/chunks/chunk-AGUSPIUP.js +2 -0
  380. package/chunks/chunk-BQ3CF3KE.js +2 -0
  381. package/chunks/chunk-C3CMJAAV.js +3 -0
  382. package/chunks/chunk-CJM7ZJ6W.js +7 -0
  383. package/chunks/chunk-CSOUJVKM.js +2 -0
  384. package/chunks/chunk-D66ZSHXR.js +2 -0
  385. package/chunks/chunk-D7MGU75P.js +2 -0
  386. package/chunks/chunk-E3GLGDGC.js +5 -0
  387. package/chunks/chunk-ENHOPPS7.js +16 -0
  388. package/chunks/chunk-EOR6EDNR.js +2 -0
  389. package/chunks/chunk-EYK25HWR.js +2 -0
  390. package/chunks/chunk-F46IELF5.js +2 -0
  391. package/chunks/chunk-FC4M2B7E.js +2 -0
  392. package/chunks/chunk-FSNYOJPJ.js +2 -0
  393. package/chunks/chunk-FUERW2DW.js +3 -0
  394. package/chunks/chunk-FXOH6TEQ.js +21 -0
  395. package/chunks/chunk-GP52JZMY.js +2 -0
  396. package/chunks/chunk-GRXX6I72.js +2 -0
  397. package/chunks/chunk-GSYHBK5Q.js +6 -0
  398. package/chunks/chunk-HNWBFJNO.js +2 -0
  399. package/chunks/chunk-IIE366LR.js +6706 -0
  400. package/chunks/chunk-IWK7PZP7.js +207 -0
  401. package/chunks/chunk-J3KCPYZT.js +2 -0
  402. package/chunks/chunk-KCLRJQ53.js +59 -0
  403. package/chunks/chunk-LU4RPLJ3.js +2 -0
  404. package/chunks/chunk-LZJYNT32.js +2 -0
  405. package/chunks/chunk-M7GW4VMR.js +27 -0
  406. package/chunks/chunk-MACBL5HF.js +2 -0
  407. package/chunks/chunk-N5NTXCJI.js +2 -0
  408. package/chunks/chunk-N5SVBCUB.js +7 -0
  409. package/chunks/chunk-N6W7ZL26.js +2 -0
  410. package/chunks/chunk-NWB7LFOK.js +131 -0
  411. package/chunks/chunk-OIQ336YE.js +16 -0
  412. package/chunks/chunk-OQNU3VPS.js +30 -0
  413. package/chunks/chunk-OTDNOWXG.js +16 -0
  414. package/chunks/chunk-PNXZWSWT.js +3 -0
  415. package/chunks/chunk-QFUV5PX6.js +2 -0
  416. package/chunks/chunk-QIN5ZBE2.js +2 -0
  417. package/chunks/chunk-QKBN5CGI.js +2 -0
  418. package/chunks/chunk-QPGTKSIQ.js +2 -0
  419. package/chunks/chunk-SIOLUFGG.js +2 -0
  420. package/chunks/chunk-TW23QKAD.js +3 -0
  421. package/chunks/chunk-U3RMPDXU.js +2 -0
  422. package/chunks/chunk-U7U3DJHF.js +2 -0
  423. package/chunks/chunk-VLXX22YO.js +2 -0
  424. package/chunks/chunk-WHD2XVT2.js +2 -0
  425. package/chunks/chunk-WTAJMYF2.js +249 -0
  426. package/chunks/chunk-WWNUAU4P.js +29 -0
  427. package/chunks/chunk-WYANV3IX.js +4 -0
  428. package/chunks/chunk-XAGZ6ZEU.js +9 -0
  429. package/chunks/chunk-XFCC2CI2.js +24 -0
  430. package/chunks/chunk-XQK7JM66.js +2 -0
  431. package/chunks/chunk-YLQXZBEL.js +2 -0
  432. package/chunks/chunk-YPV2X2RG.js +2 -0
  433. package/chunks/chunk-Z6BHCXKT.js +25 -0
  434. package/chunks/chunk-Z6HBNJCA.js +8 -0
  435. package/chunks/chunk-ZQKVUPKA.js +2 -0
  436. package/chunks/chunk-ZQOALVGL.js +2 -0
  437. package/chunks/clipboard-image-PQPC4EHR.js +2 -0
  438. package/chunks/data-dir-LDVKDCJ2.js +2 -0
  439. package/chunks/dist-2BRD4JFU.js +11 -0
  440. package/chunks/dist-EXKHRFQO.js +5 -0
  441. package/chunks/emscripten-module-RD6P2XH5.js +2 -0
  442. package/chunks/emscripten-module-WYNDFH3N.js +2 -0
  443. package/chunks/emscripten-module-XPTEOIWW.js +2 -0
  444. package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
  445. package/chunks/ffi-IO7WZQNG.js +2 -0
  446. package/chunks/ffi-M5UP5J6C.js +2 -0
  447. package/chunks/ffi-ORLOPBB3.js +2 -0
  448. package/chunks/ffi-OUPK6AY6.js +2 -0
  449. package/chunks/google-UJAPMFAB.js +2 -0
  450. package/chunks/google-vertex-VLSF55PW.js +2 -0
  451. package/chunks/install-source-JTIUC4G4.js +2 -0
  452. package/chunks/launcher-FCZ3EDBF.js +61 -0
  453. package/chunks/lifecycle-GY435YMF.js +2 -0
  454. package/chunks/main-TQGGRHTS.js +13 -0
  455. package/chunks/mistral-ZJZUEF2X.js +3 -0
  456. package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
  457. package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
  458. package/chunks/multipart-parser-L6M455MS.js +2 -0
  459. package/chunks/network-proxy-U72JCK2I.js +2 -0
  460. package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
  461. package/chunks/openai-completions-D32YW6KL.js +2 -0
  462. package/chunks/openai-responses-ZCGSENM4.js +2 -0
  463. package/chunks/openrouter-G2EHY5BD.js +2 -0
  464. package/chunks/otel-OHXIZ666.js +2 -0
  465. package/chunks/package-contract-GVXTMJ3N.js +2 -0
  466. package/chunks/pdfjs-SHZAF7PF.js +107 -0
  467. package/chunks/photon_rs-C52RL4CI.js +3 -0
  468. package/chunks/plugin-command-OSAFHS7C.js +2 -0
  469. package/chunks/provider-command-SKTCHD4E.js +2 -0
  470. package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
  471. package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
  472. package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
  473. package/chunks/skills-command-XXXEZAG6.js +2 -0
  474. package/chunks/src-DNIDEMVV.js +2 -0
  475. package/chunks/src-IBHIRTD7.js +2 -0
  476. package/chunks/telemetry-J7ZLGF5X.js +2 -0
  477. package/chunks/telemetry-command-COQG2AKK.js +5 -0
  478. package/chunks/tools-WDBB2JKV.js +2 -0
  479. package/chunks/undici-TUGHZJSA.js +2 -0
  480. package/chunks/update-NB6OD572.js +14 -0
  481. package/chunks/update-hint-ED7O67WU.js +3 -0
  482. package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
  483. package/cli.js +5 -0
  484. package/configs/data-minimal.yaml +50 -0
  485. package/embedded/alran-tools/cli.mjs +4961 -0
  486. package/embedded/alran-tools/manifest.json +25 -0
  487. package/emscripten-module.wasm +0 -0
  488. package/image-preview-worker.js +2 -0
  489. package/internal-bin/alran-tools +9 -0
  490. package/internal-bin/alran-tools.cmd +8 -0
  491. package/matrix-mcp-stdio.js +4 -0
  492. package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
  493. package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
  494. package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
  495. package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
  496. package/package.json +38 -4
  497. package/photon_rs_bg.wasm +0 -0
  498. package/quickjs-worker.js +152 -0
  499. package/vendor/java-proxy-agent/build.ts +97 -0
  500. package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
  501. package/vendor/seccomp/arm64/apply-seccomp +0 -0
  502. package/vendor/seccomp/build.ts +74 -0
  503. package/vendor/seccomp/x64/apply-seccomp +0 -0
  504. package/vendor/srt-win/arm64/srt-win.exe +0 -0
  505. package/vendor/srt-win/build.ts +40 -0
  506. package/vendor/srt-win/x64/srt-win.exe +0 -0
@@ -0,0 +1,284 @@
1
+ """Shared helpers for read_pdf_vision.py — page-spec parsing, output spill,
2
+ stderr progress, range coalescing.
3
+
4
+ Originally written for three read_pdf_* scripts; ptot and ocr have since been
5
+ replaced by inline cookbook recipes in SKILL.md, leaving vision as the only
6
+ consumer. Kept under the same name and module path because the helpers are
7
+ generic read-side concerns (not vision-specific) — a future cookbook helper
8
+ script could pick them up.
9
+
10
+ Stdlib-only on purpose: every consumer should be able to
11
+ `from _pdf_read_lib import ...` without pulling in a heavyweight dep tree.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import hashlib
18
+ import json
19
+ import os
20
+ import sys
21
+ from pathlib import Path
22
+ from typing import Iterable
23
+
24
+ DEFAULT_MAX_STDOUT_BYTES = 2 * 1024
25
+
26
+
27
+ class PagesParseError(ValueError):
28
+ pass
29
+
30
+
31
+ def parse_pages(raw: str | None) -> list[int] | None:
32
+ """Parse "1-10" / "1,3,5" / "1-3,7,10-15" / "all" / None.
33
+
34
+ Returns sorted, deduped, 1-based page numbers; or None for "all".
35
+ """
36
+ if raw is None:
37
+ return None
38
+ s = raw.strip()
39
+ if not s or s.lower() == "all":
40
+ return None
41
+ out: set[int] = set()
42
+ for seg_raw in s.replace(" ", ",").split(","):
43
+ seg = seg_raw.strip()
44
+ if not seg:
45
+ continue
46
+ if "-" in seg:
47
+ parts = seg.split("-")
48
+ if len(parts) != 2:
49
+ raise PagesParseError(f'Invalid page range "{seg}"')
50
+ try:
51
+ lo, hi = int(parts[0]), int(parts[1])
52
+ except ValueError as e:
53
+ raise PagesParseError(f'Invalid page range "{seg}"') from e
54
+ if lo < 1 or hi < 1 or lo > hi:
55
+ raise PagesParseError(f'Invalid page range "{seg}"')
56
+ out.update(range(lo, hi + 1))
57
+ else:
58
+ try:
59
+ n = int(seg)
60
+ except ValueError as e:
61
+ raise PagesParseError(f'Invalid page number "{seg}"') from e
62
+ if n < 1:
63
+ raise PagesParseError(f'Invalid page number "{seg}"')
64
+ out.add(n)
65
+ return sorted(out)
66
+
67
+
68
+ def validate_pages(pages: Iterable[int], total_pages: int) -> None:
69
+ for p in pages:
70
+ if p > total_pages:
71
+ raise PagesParseError(
72
+ f"Page {p} is out of range (PDF has {total_pages} pages)"
73
+ )
74
+
75
+
76
+ def clamp_pages(pages: Iterable[int], total_pages: int) -> tuple[list[int], list[int]]:
77
+ """Split a requested page list into (kept, dropped).
78
+
79
+ `kept` — pages within [1, total_pages]
80
+ `dropped` — pages beyond total_pages
81
+
82
+ Used by callers that prefer "trim to what's actually there" over a hard
83
+ failure when the user / model asked for pages past the end of the PDF
84
+ (a common failure mode: the model guesses 36 pages on a 10-page paper).
85
+ """
86
+ kept: list[int] = []
87
+ dropped: list[int] = []
88
+ for p in pages:
89
+ (kept if p <= total_pages else dropped).append(p)
90
+ return kept, dropped
91
+
92
+
93
+ def format_pages(pages: list[int]) -> str:
94
+ """Compress a sorted page list — [1,2,3,7,10,11,12] → "1-3,7,10-12"."""
95
+ if not pages:
96
+ return ""
97
+ groups: list[str] = []
98
+ start = pages[0]
99
+ prev = start
100
+ for cur in pages[1:]:
101
+ if cur == prev + 1:
102
+ prev = cur
103
+ continue
104
+ groups.append(str(start) if start == prev else f"{start}-{prev}")
105
+ start = cur
106
+ prev = cur
107
+ groups.append(str(start) if start == prev else f"{start}-{prev}")
108
+ return ",".join(groups)
109
+
110
+
111
+ def cache_dir() -> Path:
112
+ """Return ~/.cache/alran/pdf-out/ — the spill destination for outputs
113
+ larger than --max-stdout-bytes (default 2 KB). Lives under $HOME so it
114
+ survives across runs and stays on the user's data partition.
115
+ """
116
+ return Path.home() / ".cache" / "alran" / "pdf-out"
117
+
118
+
119
+ def hash_content(content: str) -> str:
120
+ return hashlib.sha256(content.encode("utf-8")).hexdigest()[:16]
121
+
122
+
123
+ def maybe_spill_to_file(content: str, ext: str, max_stdout_bytes: int) -> str:
124
+ """If content > threshold, spill to ~/.cache/alran/pdf-out/<hash>.<ext>
125
+ and return a wrapper (markdown banner or JSON envelope) with preview.
126
+ """
127
+ total_bytes = len(content.encode("utf-8"))
128
+ if max_stdout_bytes == 0 or total_bytes <= max_stdout_bytes:
129
+ return content
130
+
131
+ d = cache_dir()
132
+ d.mkdir(parents=True, exist_ok=True)
133
+ target = d / f"{hash_content(content)}.{ext}"
134
+ target.write_text(content, encoding="utf-8")
135
+
136
+ # Slice by bytes (CJK-safe via 'ignore' on incomplete tail).
137
+ buf = content.encode("utf-8")
138
+ preview = buf[:max_stdout_bytes].decode("utf-8", errors="ignore")
139
+ preview_bytes = len(preview.encode("utf-8"))
140
+
141
+ if ext == "json":
142
+ return (
143
+ json.dumps(
144
+ {
145
+ "truncated": True,
146
+ "totalBytes": total_bytes,
147
+ "outputFile": str(target),
148
+ "previewBytes": preview_bytes,
149
+ "preview": preview,
150
+ },
151
+ ensure_ascii=False,
152
+ indent=2,
153
+ )
154
+ + "\n"
155
+ )
156
+ # markdown
157
+ return "\n".join(
158
+ [
159
+ "<!-- alran-pdf: output truncated, full text spilled to disk -->",
160
+ f"> ⚠ Full output: **{total_bytes:,} bytes** → `{target}`",
161
+ f"> Showing first **{preview_bytes:,} bytes** below.",
162
+ "> Read the file with `cat` / `grep`, or re-run with narrower `--pages`.",
163
+ "",
164
+ preview,
165
+ ]
166
+ )
167
+
168
+
169
+ def add_common_args(p: argparse.ArgumentParser) -> None:
170
+ """Common --input / --pages / --json / --max-stdout-bytes flags."""
171
+ p.add_argument(
172
+ "--input", required=True, help="Path to the PDF file (required)."
173
+ )
174
+ p.add_argument(
175
+ "--pages",
176
+ default=None,
177
+ help='Pages to read: "1-20", "1,3,5", "1-3,7,10-15", or "all" (default).',
178
+ )
179
+ p.add_argument(
180
+ "--json",
181
+ action="store_true",
182
+ help="Output structured JSON instead of Markdown.",
183
+ )
184
+ p.add_argument(
185
+ "--max-stdout-bytes",
186
+ type=int,
187
+ default=DEFAULT_MAX_STDOUT_BYTES,
188
+ help=(
189
+ f"If output exceeds this many bytes, spill the full text to "
190
+ f"~/.cache/alran/pdf-out/<hash>.{{md,json}} and only print a "
191
+ f"preview + path to stdout. Set 0 to disable. "
192
+ f"(default {DEFAULT_MAX_STDOUT_BYTES})"
193
+ ),
194
+ )
195
+
196
+
197
+ def emit(content: str, ext: str, max_stdout_bytes: int) -> None:
198
+ """Write content (after optional spill) to stdout."""
199
+ out = maybe_spill_to_file(content, ext, max_stdout_bytes)
200
+ sys.stdout.write(out)
201
+ if not out.endswith("\n"):
202
+ sys.stdout.write("\n")
203
+
204
+
205
+ def info(msg: str) -> None:
206
+ """Stderr progress line — not part of the structured output."""
207
+ sys.stderr.write(f" {msg}\n")
208
+ sys.stderr.flush()
209
+
210
+
211
+ def warn(msg: str) -> None:
212
+ sys.stderr.write(f" ⚠ {msg}\n")
213
+ sys.stderr.flush()
214
+
215
+
216
+ def die(msg: str, code: int = 1) -> None:
217
+ sys.stderr.write(f" ✖ {msg}\n")
218
+ sys.stderr.flush()
219
+ sys.exit(code)
220
+
221
+
222
+ def resolve_pages_or_exit(raw: str | None, total_pages: int) -> list[int]:
223
+ """Parse a `--pages` spec and clamp it to the PDF's actual page count.
224
+
225
+ Behaviour:
226
+ - parse failure (malformed range) → die() with the parse error
227
+ - "all" / None → return [1..total_pages]
228
+ - some requested pages exceed the total → drop them, warn() once,
229
+ keep the rest
230
+ - every requested page exceeds the total → die() (nothing to do)
231
+ """
232
+ try:
233
+ parsed = parse_pages(raw)
234
+ except PagesParseError as e:
235
+ die(str(e))
236
+ if parsed is None:
237
+ return list(range(1, total_pages + 1))
238
+ kept, dropped = clamp_pages(parsed, total_pages)
239
+ if dropped:
240
+ warn(
241
+ f"Requested pages out of range (PDF has {total_pages} pages); "
242
+ f"dropping {format_pages(dropped)}, keeping {format_pages(kept) or '(none)'}"
243
+ )
244
+ if not kept:
245
+ die(
246
+ f"No requested pages fall within the PDF's {total_pages} pages "
247
+ f"(requested: {format_pages(parsed)})"
248
+ )
249
+ return kept
250
+
251
+
252
+ def resolve_input_or_exit(path: str) -> Path:
253
+ p = Path(path).expanduser().resolve()
254
+ if not p.is_file():
255
+ die(f"File not found: {p}")
256
+ return p
257
+
258
+
259
+ # Coalesce a page list into contiguous spans — used by the vision script to
260
+ # batch (lo, hi) ranges to pdf2image instead of one render call per page.
261
+ def to_ranges(pages: list[int]) -> list[tuple[int, int]]:
262
+ if not pages:
263
+ return []
264
+ ranges: list[tuple[int, int]] = []
265
+ start = pages[0]
266
+ prev = start
267
+ for cur in pages[1:]:
268
+ if cur == prev + 1:
269
+ prev = cur
270
+ continue
271
+ ranges.append((start, prev))
272
+ start = cur
273
+ prev = cur
274
+ ranges.append((start, prev))
275
+ return ranges
276
+
277
+
278
+ # Sanity: callers should always run with python3 ≥ 3.9 (matches macOS default).
279
+ def _ensure_py39() -> None:
280
+ if sys.version_info < (3, 9):
281
+ die(f"Python 3.9+ required, got {sys.version_info[:2]}")
282
+
283
+
284
+ _ensure_py39()
File without changes
@@ -0,0 +1,153 @@
1
+ """Apply user-supplied values to AcroForm fields.
2
+
3
+ Reads the fillable PDF, validates the values against the schema
4
+ discovered by ``scripts.pdf_inspect.acroform_inspect``, and writes a new
5
+ PDF with the field values populated.
6
+
7
+ The value-config JSON is an array of records::
8
+
9
+ [
10
+ {
11
+ "qname": "person.last_name",
12
+ "page_no": 1,
13
+ "set_to": "Simpson"
14
+ },
15
+ {
16
+ "qname": "is_adult",
17
+ "page_no": 1,
18
+ "set_to": "/On" # for checkboxes use the on_value
19
+ }
20
+ ]
21
+
22
+ Run from the skill root::
23
+
24
+ python -m scripts.fill.acroform_apply input.pdf values.json output.pdf
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import json
30
+ import sys
31
+
32
+ from pypdf import PdfReader, PdfWriter
33
+
34
+ from scripts.lib.acroform_io import (
35
+ enumerate_acroform_fields,
36
+ patch_pypdf_inheritance,
37
+ )
38
+ from scripts.lib.cli_utils import emit, fail, make_parser
39
+
40
+
41
+ def value_violation(known_record: dict, supplied_value) -> str | None:
42
+ field_type = known_record["type"]
43
+ qname = known_record["qname"]
44
+ if field_type == "checkbox":
45
+ on = known_record["on_value"]
46
+ off = known_record["off_value"]
47
+ if supplied_value != on and supplied_value != off:
48
+ return (
49
+ f'ERROR: invalid value "{supplied_value}" for checkbox "{qname}". '
50
+ f'Use on_value="{on}" or off_value="{off}".'
51
+ )
52
+ elif field_type == "radio_group":
53
+ valid = [opt["set_to"] for opt in known_record["radio_choices"]]
54
+ if supplied_value not in valid:
55
+ return (
56
+ f'ERROR: invalid value "{supplied_value}" for radio "{qname}". '
57
+ f"Valid values: {valid}"
58
+ )
59
+ elif field_type == "choice":
60
+ valid = [opt["set_to"] for opt in known_record["choice_options"]]
61
+ if supplied_value not in valid:
62
+ return (
63
+ f'ERROR: invalid value "{supplied_value}" for choice "{qname}". '
64
+ f"Valid values: {valid}"
65
+ )
66
+ return None
67
+
68
+
69
+ def apply_acroform_values(
70
+ src_pdf: str,
71
+ value_cfg: str,
72
+ dst_pdf: str,
73
+ *,
74
+ quiet: bool = False,
75
+ ) -> int:
76
+ with open(value_cfg) as handle:
77
+ supplied = json.load(handle)
78
+
79
+ values_by_page: dict[int, dict[str, object]] = {}
80
+ for entry in supplied:
81
+ if "set_to" not in entry:
82
+ continue
83
+ page = entry["page_no"]
84
+ values_by_page.setdefault(page, {})[entry["qname"]] = entry["set_to"]
85
+
86
+ pdf_doc = PdfReader(src_pdf)
87
+ record_by_qname = {r["qname"]: r for r in enumerate_acroform_fields(pdf_doc)}
88
+
89
+ failed = False
90
+ for entry in supplied:
91
+ known_record = record_by_qname.get(entry["qname"])
92
+ if not known_record:
93
+ failed = True
94
+ print(f"ERROR: `{entry['qname']}` is not a known field id")
95
+ continue
96
+ if entry["page_no"] != known_record["page_no"]:
97
+ failed = True
98
+ print(
99
+ f"ERROR: page_no mismatch for `{entry['qname']}` "
100
+ f"(supplied {entry['page_no']}, expected {known_record['page_no']})"
101
+ )
102
+ continue
103
+ if "set_to" in entry:
104
+ problem = value_violation(known_record, entry["set_to"])
105
+ if problem:
106
+ failed = True
107
+ print(problem)
108
+
109
+ if failed:
110
+ sys.exit(1)
111
+
112
+ out_doc = PdfWriter(clone_from=pdf_doc)
113
+ for page_no, values in values_by_page.items():
114
+ out_doc.update_page_form_field_values(
115
+ out_doc.pages[page_no - 1],
116
+ values,
117
+ auto_regenerate=False,
118
+ )
119
+ out_doc.set_need_appearances_writer(True)
120
+
121
+ with open(dst_pdf, "wb") as handle:
122
+ out_doc.write(handle)
123
+
124
+ emit(f"Wrote filled PDF to {dst_pdf}", quiet=quiet)
125
+ return len(supplied)
126
+
127
+
128
+ def main(argv: list[str] | None = None) -> int:
129
+ parser = make_parser(
130
+ "acroform_apply",
131
+ "Fill AcroForm fields using a JSON config and write a new PDF.",
132
+ )
133
+ parser.add_argument("src_pdf", help="Input fillable PDF.")
134
+ parser.add_argument("value_cfg", help="JSON file describing the values to set.")
135
+ parser.add_argument("dst_pdf", help="Output PDF path.")
136
+ args = parser.parse_args(argv)
137
+
138
+ patch_pypdf_inheritance()
139
+
140
+ try:
141
+ apply_acroform_values(
142
+ args.src_pdf,
143
+ args.value_cfg,
144
+ args.dst_pdf,
145
+ quiet=args.quiet,
146
+ )
147
+ except FileNotFoundError as exc:
148
+ fail(f"File not found: {exc.filename}", code=2)
149
+ return 0
150
+
151
+
152
+ if __name__ == "__main__":
153
+ sys.exit(main())
@@ -0,0 +1,109 @@
1
+ """Lay text on top of a non-fillable PDF using FreeText annotations.
2
+
3
+ Consumes the new-style ``fields.json`` produced by the operator (see
4
+ docs/forms-guide.md, "Overlay schema") and writes a new PDF with each
5
+ slot populated by a FreeText annotation. Coordinates can come from
6
+ either the PDF (``pdf_w``/``pdf_h``) or a rasterised image
7
+ (``img_w``/``img_h``); the script picks the right transform per page.
8
+
9
+ Run from the skill root::
10
+
11
+ python -m scripts.fill.overlay_apply input.pdf fields.json out.pdf
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import sys
18
+
19
+ from pypdf import PdfReader, PdfWriter
20
+ from pypdf.annotations import FreeText
21
+
22
+ from scripts.lib.cli_utils import emit, fail, make_parser
23
+ from scripts.lib.geometry import image_box_to_pdf_rect, pdf_box_to_pypdf_rect
24
+
25
+
26
+ def apply_overlay_text(
27
+ src_pdf: str,
28
+ cfg_path: str,
29
+ dst_pdf: str,
30
+ *,
31
+ quiet: bool = False,
32
+ ) -> int:
33
+ with open(cfg_path, "r") as handle:
34
+ cfg = json.load(handle)
35
+
36
+ pdf_doc = PdfReader(src_pdf)
37
+ out_doc = PdfWriter()
38
+ out_doc.append(pdf_doc)
39
+
40
+ page_dim: dict[int, tuple[float, float]] = {}
41
+ for idx, pg in enumerate(pdf_doc.pages):
42
+ mb = pg.mediabox
43
+ page_dim[idx + 1] = (float(mb.width), float(mb.height))
44
+
45
+ written = 0
46
+ for slot in cfg.get("slots", []):
47
+ page_no = slot["page_no"]
48
+ meta = next(p for p in cfg["pages"] if p["page_no"] == page_no)
49
+ pdf_w, pdf_h = page_dim[page_no]
50
+
51
+ if "pdf_w" in meta:
52
+ pypdf_rect = pdf_box_to_pypdf_rect(slot["slot_box"], pdf_h)
53
+ else:
54
+ pypdf_rect = image_box_to_pdf_rect(
55
+ slot["slot_box"],
56
+ meta["img_w"],
57
+ meta["img_h"],
58
+ pdf_w,
59
+ pdf_h,
60
+ )
61
+
62
+ glyph_spec = slot.get("value")
63
+ if not glyph_spec or not glyph_spec.get("text"):
64
+ continue
65
+ text = glyph_spec["text"]
66
+ face = glyph_spec.get("face", "Arial")
67
+ size = f"{glyph_spec.get('size', 14)}pt"
68
+ color = glyph_spec.get("color", "000000")
69
+
70
+ annot = FreeText(
71
+ text=text,
72
+ rect=pypdf_rect,
73
+ font=face,
74
+ font_size=size,
75
+ font_color=color,
76
+ border_color=None,
77
+ background_color=None,
78
+ )
79
+ out_doc.add_annotation(page_number=page_no - 1, annotation=annot)
80
+ written += 1
81
+
82
+ with open(dst_pdf, "wb") as handle:
83
+ out_doc.write(handle)
84
+
85
+ emit(f"Wrote overlaid PDF to {dst_pdf} ({written} annotations)", quiet=quiet)
86
+ return written
87
+
88
+
89
+ def main(argv: list[str] | None = None) -> int:
90
+ parser = make_parser(
91
+ "overlay_apply",
92
+ "Stamp text annotations onto a PDF based on a fields.json config.",
93
+ )
94
+ parser.add_argument("src_pdf", help="Input PDF (any kind).")
95
+ parser.add_argument("cfg_path", help="fields.json config (new schema).")
96
+ parser.add_argument("dst_pdf", help="Output PDF path.")
97
+ args = parser.parse_args(argv)
98
+
99
+ try:
100
+ apply_overlay_text(args.src_pdf, args.cfg_path, args.dst_pdf, quiet=args.quiet)
101
+ except FileNotFoundError as exc:
102
+ fail(f"File not found: {exc.filename}", code=2)
103
+ except KeyError as exc:
104
+ fail(f"fields.json missing required key: {exc}", code=2)
105
+ return 0
106
+
107
+
108
+ if __name__ == "__main__":
109
+ sys.exit(main())
File without changes