@softure-ai/blog 0.0.0-stage → 0.1.6

package/skill/references/structure.md

@@ -0,0 +1,69 @@
+# Structure for readers and for AI citations
+
+AI assistants quote a fragment, not a whole text, and most quotes come from the first third of a
+text. Numbers and quotes with a source raise the chance of being cited. Hence the order:
+
+1. **Lead (one or two paragraphs, up to {{leadWordsArticle}} words):** the answer to the title's
+   question and one concrete number with its footnote (rule `lead-number`). No warm-up about "these
+   times" and no announcement of what follows.
+2. **Context in one or two sentences:** where the number comes from.
+3. **`##` sections as questions** people ask assistants. The first sentence under a question is a
+   self-contained answer that can be cut out and quoted (rule `section-answer`), up to
+   {{answerWords}} words.
+4. **A worked example** for a concrete person or case: inputs, result, a small table (two to six
+   rows) and one sentence that reads one number out of it. This is what generic summaries lack.
+5. **When it does not work:** the condition under which the answer turns around. It separates a
+   guide from an advert and is what comparisons quote.
+6. **A checklist or steps** only when the reader really does something; do not turn prose into a
+   list of "**Label:** text" items.
+
+Length: an article of {{articleWordsMin}} to {{articleWordsMax}} words, a glossary term of
+{{termWordsMin}} to {{termWordsMax}} words with a lead of up to {{leadWordsTerm}}.
+
+## Footnotes
+
+- `[^id]` right after the sentence with the number; definitions at the end of the file.
+{{#ymyl}}
+- A source: `[^limit]: <source name>: https://…`, and the same address stands in `sources` in the
+  frontmatter (rule `footnote-not-in-sources`).
+{{#ownCalculationMark}}
+- Your own calculation: `[^calc]: {{ownCalculationMark}}: <inputs>, as of YYYY-MM-DD.` Write the inputs
+  so that anyone can repeat the calculation and get the same result.
+{{/ownCalculationMark}}
+- Every amount, percentage and number from 1000 up carries a footnote (rule `number-source`).
+  Years, ages, small counts and legal references need none.
+{{/ymyl}}
+{{^ymyl}}
+- Footnote numbers a reader might doubt, with the source's address.
+{{/ymyl}}
+
+## Metadata
+
+- `title` up to {{titleChars}} characters, with the question or the number; `description`
+  {{descriptionCharsMin}} to {{descriptionCharsMax}} characters, with the answer.
+- `summary`: the "in short" box above the body, a few sentences with numbers an assistant can quote.
+- `current_as_of`: the day the facts were checked against their sources. Change it only after
+  checking every number, never for a typo fix.
+- `faq`: two to five `question`/`answer` pairs, each answer one sentence with a number.
+- `cluster`: the topic, for "read next" lists. `pillar: true` only for the main text of a cluster
+  (one per cluster); the others link to it.
+{{#fields}}
+- The app's own keys: {{fieldKeys}}. Their meaning is the app's; follow the examples in
+  `{{contentDir}}`.
+{{/fields}}
+
+## Links
+
+- Internal, at least {{internalLinksArticle}}: one or two texts of the same cluster
+  (`{{articlesPath}}/<slug>`), a glossary term at the first use of a concept
+  (`{{termsPath}}/<slug>`; the renderer links the first mention of a term's forms by itself, so link
+  by hand only where no form matches), and the app's pages.
+- External: primary sources only (laws, official statistics, the issuer's own documents). No
+  competitors' blogs and no comparison sites.
+
+## Disclaimers
+
+A disclaimer such as "this is not investment advice" belongs to the page template, not the text.
+{{#ymyl}}
+The text guards the other side: no promise of a gain and no order to buy (rule `profit-promise`).
+{{/ymyl}}

package/skill/references/template.md

@@ -0,0 +1,86 @@
+# The file `{{contentDir}}/<slug>.md`
+
+One file per text; the file name is the slug plus `.md`. The frontmatter keys are fixed and an
+unknown key is an error (rule `file`). Copy a text of `{{contentDir}}` that passes the gate when
+there is one; otherwise start from this:
+
+```markdown
+---
+id: <stable-kebab-key>          # given once, never changed
+slug: <kebab-file-name>         # the address under {{articlesPath}}/; equals the file name
+kind: article                   # or: term (a glossary definition)
+cluster: <topic>                # optional: the topic for "read next" lists
+pillar: false                   # true only for the main text of the cluster
+title: <the question or the number, up to {{titleChars}} characters>
+description: <the answer with its number, {{descriptionCharsMin}} to {{descriptionCharsMax}} characters>
+summary: <a few sentences with the answer and its numbers>
+status: draft                   # draft | published | withdrawn
+current_as_of: YYYY-MM-DD       # the day the facts were checked
+sources:
+  - name: <name of the act, dataset or document>
+    url: https://<primary source>
+faq:
+  - question: <the question as a person asks it>
+    answer: <one sentence with a number>
+---
+
+<Lead: the answer and its number[^source]. A second sentence with the worked example's number.>
+
+<Context in one or two sentences.>
+
+## <The question a person asks?>
+
+<The answer in the first sentence, with a footnote on the number[^source].>
+
+## <What does it mean for a concrete case?>
+
+<Inputs, result, a small table, and one sentence that reads a number out of it.>
+
+## <When does it not work?>
+
+<The condition under which the answer turns around.>
+
+[^source]: <Source name>: https://<the same address as in sources>
+```
+{{#fields}}
+
+The app adds its own keys: {{fieldKeys}}. Look up their use in a published text of
+`{{contentDir}}`.
+{{/fields}}
+{{#reservedSlugs}}
+
+Slugs taken by the blog's own pages, never usable for a text: {{reservedSlugList}}.
+{{/reservedSlugs}}
+
+## A glossary term (`kind: term`)
+
+The same folder and format, at `{{termsPath}}/<slug>`. The differences:
+
+```markdown
+---
+id: <kebab-key>
+slug: <kebab-key>
+kind: term
+title: <the name of the concept, as the glossary index lists it>
+description: <the definition in one sentence, with a number>
+forms:                          # required: the phrases that link to this term from articles
+  - <phrase as it stands in texts>
+  - <another inflected form>
+status: draft
+current_as_of: YYYY-MM-DD
+sources:
+  - name: <source>
+    url: https://<primary source>
+---
+
+<The definition in the first sentence, with a number and its footnote[^source]. {{termWordsMin}} to
+{{termWordsMax}} words in all, a lead of up to {{leadWordsTerm}}.>
+```
+
+- **Forms** are phrases, not single words: "bridge to retirement", not "bridge", or every sentence
+  about a bridge gets a link. Each inflected form separately; a capital at the start of a sentence
+  matches by itself.
+- The renderer links the **first** mention of a form in the prose of an article (not in a heading,
+  link, code or footnote); a manual link is needed only where no form matches.
+- **Slug change:** change `slug` and rename the file, keep `id`; the old address redirects.
+- **Withdrawal:** `status: withdrawn`; never delete the file.

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure-blog` executable. All logic lives in command.ts and run.ts, which the tests call directly.
+import { runBlogCommand } from "./command.js";
+
+process.exitCode = await runBlogCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,49 @@
+// The `softure-blog` bin. It loads the app's config through `@softure-ai/core/cli`, like
+// `softure migrate` (@softure-ai/db): the file must be loadable by Node itself (`.js`/`.mjs`, or `.ts`
+// where Node strips types). Anything else uses an app script with `runBlogCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { BLOG_USAGE, EXIT_FAILED, EXIT_OK, EXIT_USAGE, parseBlogCommand, runBlogCli, type BlogCommand, type CliOutput } from "./run.js";
+
+export interface RunBlogCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runBlogCli", packageName: "@softure-ai/blog" };
+
+// The commands that never connect, so a CI job runs them with a config that has no database URL.
+// Any other command (and a new one, until it is listed here) needs the database.
+const COMMANDS_WITHOUT_DATABASE: ReadonlySet<BlogCommand["kind"]> = new Set(["check", "skill-install"]);
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Checks the arguments, loads the config and runs `runBlogCli`. A usage error never loads the config. */
+export async function runBlogCommand(options: RunBlogCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const taken = takeConfigOption(options.argv);
+  if (!taken.ok) return refuseUsage(output, taken.problem);
+  const command = parseBlogCommand(taken.argv);
+  if (typeof command === "string") return refuseUsage(output, command);
+  if (command.kind === "help") {
+    output.log(BLOG_USAGE);
+    return EXIT_OK;
+  }
+
+  const database = COMMANDS_WITHOUT_DATABASE.has(command.kind) ? "optional" : "required";
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath: taken.configPath, appScript: APP_SCRIPT, database });
+  if (!loaded.ok) {
+    output.error(`softure-blog: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runBlogCli({ config: loaded.config, argv: taken.argv, cwd: options.cwd, output });
+}
+
+function refuseUsage(output: CliOutput, problem: string): number {
+  output.error(`softure-blog: ${problem}`);
+  output.error(BLOG_USAGE);
+  return EXIT_USAGE;
+}

package/src/cli/index.ts

@@ -0,0 +1,20 @@
+// `@softure-ai/blog/cli`: the `softure-blog` command for app scripts and container bundles.
+export { runBlogCommand, type RunBlogCommandOptions } from "./command.js";
+export { BLOG_USAGE, EXIT_FAILED, EXIT_OK, EXIT_USAGE, parseBlogCommand, runBlogCli, type BlogCommand, type CliOutput, type RunBlogCliOptions } from "./run.js";
+export {
+  APP_SECTIONS_FILE,
+  DEFAULT_SKILL_COMMAND,
+  DEFAULT_SKILL_DIR,
+  fillRulesTables,
+  findTemplateRuleIds,
+  getSkillValues,
+  listTemplateFiles,
+  readSkillTemplate,
+  renderAppSections,
+  renderBlogSkill,
+  renderSkillTemplate,
+  SKILL_MARKER,
+  type RenderBlogSkillOptions,
+  type SkillFile,
+  type SkillValues,
+} from "./skill.js";