@nowline/mcp 0.7.0 → 0.8.0

package/src/reference-cheatsheet.ts

@@ -0,0 +1,47 @@
+// Condensed DSL reference for the MCP `reference` discovery tool (format: condensed).
+
+export const REFERENCE_CHEATSHEET = `# Nowline DSL — condensed reference
+
+Every file starts with \`nowline v1\` on line 1.
+
+## Roadmap directive
+
+\`\`\`
+roadmap <id> "<title>" start:YYYY-MM-DD scale:2w
+\`\`\`
+
+Common keys: \`start:\`, \`scale:\`, \`length:\`, \`locale:\`, \`theme:\`, \`author:\`, \`calendar:\`.
+
+## Swimlanes and items
+
+\`\`\`
+swimlane <id> "<title>"
+  item <id> "<title>" duration:3w
+\`\`\`
+
+Entity types: \`swimlane\`, \`group\`, \`parallel\`, \`item\`, \`milestone\`, \`anchor\`.
+
+Items need \`duration:\` or \`size:\`. Use 2-space indentation under parents.
+
+## Item properties
+
+\`duration:\` (or \`size:\`), \`status:\`, \`remaining:\`, \`owner:\`, \`after:\`, \`before:\`, \`labels:\`, \`link:\`, \`style:\`.
+
+There is NO \`progress:\` or \`color:\` key. Show completion with \`status:\` + \`remaining:\`; set visuals with a \`style:\` reference (see full reference).
+
+## Progress & status
+
+\`\`\`
+item api "API redesign" duration:4w status:in-progress remaining:40%
+\`\`\`
+
+\`status:\` values: \`planned\`, \`in-progress\` (alias \`active\`), \`done\` (alias \`completed\`), \`at-risk\`, \`blocked\`, or a custom \`status\` you declare earlier.
+
+\`remaining:\` is the work *left*, written as a percent (\`40%\`) or an effort literal (\`1w\`). So an item that is 60% complete is \`remaining:40%\`. Omit \`remaining:\` for a fully open or fully done bar.
+
+## Config / includes (before roadmap)
+
+\`config\` blocks, \`include "path.nowline"\` — see full reference for ordering rules.
+
+Call \`reference\` with \`format: "full"\` for the complete man page, or \`examples\` for sample files.
+`;

package/src/schema-vocab.ts

@@ -0,0 +1,55 @@
+// Structured key vocabulary for the MCP `schema` discovery tool.
+//
+// This is the one place whose whole job is to give agents ACCURATE DSL
+// keys so they stop hallucinating. Every key below is a real DSL token
+// (verified against specs/dsl.md and the man page) — render/CLI options
+// like `theme` or `now` are deliberately excluded because they are not
+// part of the `.nowline` source language.
+
+export const SCHEMA_VOCABULARY = {
+    // Keys valid on the `nowline` directive line (`locale`) and the
+    // `roadmap` declaration line. NOT render/CLI options (`theme`, `now`).
+    directiveKeys: [
+        'locale',
+        'author',
+        'start',
+        'scale',
+        'length',
+        'calendar',
+        'logo',
+        'logo-size',
+    ],
+    // Roadmap-section keywords — the declarable entity types.
+    entityTypes: [
+        'swimlane',
+        'item',
+        'parallel',
+        'group',
+        'person',
+        'team',
+        'anchor',
+        'label',
+        'size',
+        'status',
+        'milestone',
+        'footnote',
+    ],
+    // Properties valid on `item` declarations: item-specific keys plus the
+    // universal properties (`labels`, `link`, `style`, `description`).
+    // Visual treatment is a single `style:` reference — raw color/style
+    // props (`bg`, `fg`, `text`, ...) live in `style`/`default` config blocks.
+    itemPropertyKeys: [
+        'status',
+        'owner',
+        'after',
+        'before',
+        'size',
+        'duration',
+        'remaining',
+        'capacity',
+        'labels',
+        'link',
+        'style',
+        'description',
+    ],
+} as const;

package/src/schemas.ts

@@ -9,9 +9,17 @@ export const DiagnosticSchema = z.object({
     file: z.string(),
     line: z.number(),
     column: z.number(),
-    severity: z.enum(['error', 'warning']),
+    severity: z.enum(['error', 'warning', 'info']),
     code: z.string(),
     message: z.string(),
+    suggestion: z.string().optional(),
+});
+
+export const InsightSchema = z.object({
+    severity: z.enum(['info', 'warning']),
+    code: z.string(),
+    message: z.string(),
+    entityId: z.string().optional(),
 });
 
 // ---- Tool output schemas ---------------------------------------------------
@@ -19,6 +27,7 @@ export const DiagnosticSchema = z.object({
 export const ValidateOutputSchema = z.object({
     ok: z.boolean(),
     diagnostics: z.array(DiagnosticSchema),
+    insights: z.array(InsightSchema).optional(),
 });
 
 export const ReadOutputSchema = z.object({
@@ -52,6 +61,7 @@ export const RenderOutputSchema = z.object({
     path: z.string().optional(),
     bytes: z.number().optional(),
     shareUrl: z.string().optional(),
+    insights: z.array(InsightSchema).optional(),
 });
 
 export const ExportOutputSchema = z.object({
@@ -77,3 +87,20 @@ export const CapabilitiesOutputSchema = z.object({
 export const ListItemsOutputSchema = z.object({
     items: z.array(z.string()),
 });
+
+export const ReferenceOutputSchema = z.object({
+    format: z.enum(['condensed', 'full']),
+    text: z.string(),
+});
+
+export const ExamplesOutputSchema = z.object({
+    names: z.array(z.string()).optional(),
+    name: z.string().optional(),
+    source: z.string().optional(),
+});
+
+export const SchemaOutputSchema = z.object({
+    directiveKeys: z.array(z.string()),
+    entityTypes: z.array(z.string()),
+    itemPropertyKeys: z.array(z.string()),
+});