@aryacode/dsh-engineering 0.8.4 → 0.9.0

package/vendor/l5x/lib/session.d.ts

@@ -12,6 +12,7 @@
  * @module dsh-engineering-l5x/session
  */
 import { type L5xDocument } from './model/index.ts';
+import { type L5xStyleProfile } from './engine/style.ts';
 import type { ExecContext } from './core/tool.ts';
 import { L5xError } from './core/errors.ts';
 import type { FsService, FsTarget } from './core/tool.ts';
@@ -93,6 +94,14 @@ export declare class ProjectSession {
      * @returns The open project.
      */
     require(projectId: string | undefined, exec?: ExecContext): Promise<ProjectSnapshot>;
+    /**
+     * Read the house style of one open project.
+     *
+     * @param projectId - Explicit handle, or undefined for the chat's only project.
+     * @param exec - Calling context.
+     * @returns The profile in the shared resources schema.
+     */
+    styleProfile(projectId: string | undefined, exec?: ExecContext): Promise<L5xStyleProfile>;
     /**
      * Resolve one path through the filesystem provider without reading it.
      *

package/vendor/l5x/lib/session.js

@@ -13,6 +13,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { L5xParseError, loadL5x } from "./model/index.js";
+import { styleProfileOf } from "./engine/style.js";
 import { L5xError } from "./core/errors.js";
 import { decodeExport } from "./fs.js";
 /** A failure raised by an analysis engine. */
@@ -130,6 +131,16 @@ export class ProjectSession {
         }
         return project;
     }
+    /**
+     * Read the house style of one open project.
+     *
+     * @param projectId - Explicit handle, or undefined for the chat's only project.
+     * @param exec - Calling context.
+     * @returns The profile in the shared resources schema.
+     */
+    async styleProfile(projectId, exec) {
+        return styleProfileOf(await this.require(projectId, exec));
+    }
     /**
      * Resolve one path through the filesystem provider without reading it.
      *

package/vendor/resources/SKILL.md

@@ -0,0 +1,27 @@
+# Engineering standards
+
+Use this skill whenever you write, change or review control code or HMI screens — before you author, not
+after.
+
+## Read first
+
+- `engineering_reference` with no arguments lists the corpus. Search it for the language and the domain
+  you are about to touch (`iec state machine`, `rockwell naming`, `view alarm`, `craft fault`), then read
+  the page. Each page carries rule IDs; cite the ID when you report a finding.
+- When a project or export is open, call `engineering_profile` **before** writing. It reports the naming,
+  idioms and visual conventions the plant already uses, with evidence and a confidence level. Follow the
+  profile where it is confident; where it is low, say so and ask.
+
+## Order of work
+
+1. Read the profile (existing project) or the standard pages (new work).
+2. Author the change with the project's own names and visual language.
+3. `engineering_review` on the draft. Fix findings you agree with; explain the ones you do not.
+4. Then run the product's own validation (`draft_validate`, `ftview_validate`, `mw_compile`).
+
+## Honesty rules
+
+- A profile is evidence, not authority: quote the counts and the source path when you rely on it.
+- A rule ID is this bundle's opinion. Never present it as a standards clause or a certification.
+- Do not reproduce standards text; link the page instead.
+- If the corpus or a profile is unavailable, say which one and continue with the product's own checks.

package/vendor/resources/lib/corpus.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Loading and searching the engineering corpus.
+ *
+ * The corpus is Markdown with front matter; `scripts/gen-resources.mjs` turns it
+ * into `index.json` and `SOURCE.json`. This module reads only those generated
+ * files plus the page bodies, so searching is deterministic and needs no model,
+ * network or tokenizer.
+ *
+ * @module dsh-engineering-resources/corpus
+ */
+/** One page as the index records it. */
+export interface PageRow {
+    readonly id: string;
+    readonly title: string;
+    readonly domain: string;
+    readonly level: string;
+    readonly basis: readonly string[];
+    readonly tags: readonly string[];
+    readonly applies_to: readonly string[];
+    readonly rules: readonly string[];
+    readonly words: number;
+    readonly bytes: number;
+    readonly sha256: string;
+}
+/** The generated index. */
+export interface CorpusIndex {
+    readonly corpus: number;
+    readonly pages: readonly PageRow[];
+}
+/** One hit from a search. */
+export interface CorpusHit {
+    readonly id: string;
+    readonly title: string;
+    readonly domain: string;
+    readonly level: string;
+    readonly rules: readonly string[];
+    readonly score: number;
+}
+/** The corpus in memory, or the reason it is unavailable. */
+export interface Corpus {
+    readonly index: CorpusIndex;
+    readonly digest: string;
+    readonly directory: string;
+}
+/**
+ * Load the index and source pin once per process.
+ *
+ * @returns The corpus.
+ * @throws when the generated files are missing, which means the build did not run.
+ */
+export declare function corpus(): Corpus;
+/**
+ * Read one page body.
+ *
+ * @param id - Page id, as listed by the contents.
+ * @returns Markdown body.
+ */
+export declare function pageBody(id: string): string;
+/**
+ * Rank pages by metadata, then by body text for the remainder.
+ *
+ * @param query - Free text, rule id, tag or page id.
+ * @param limit - Most hits to return.
+ * @param domain - Optional domain filter.
+ * @returns Ranked hits, best first.
+ */
+export declare function search(query: string, limit?: number, domain?: string): readonly CorpusHit[];
+/** Domain order for the contents listing. */
+export declare const DOMAINS: readonly ["iec", "rockwell", "yaskawa", "view", "optix", "craft"];
+/** The contents, grouped by domain, with word counts. */
+export declare function contents(): {
+    domains: readonly string[];
+    pages: readonly {
+        id: string;
+        title: string;
+        domain: string;
+        level: string;
+        words: number;
+    }[];
+};

package/vendor/resources/lib/corpus.js

@@ -0,0 +1,126 @@
+/**
+ * Loading and searching the engineering corpus.
+ *
+ * The corpus is Markdown with front matter; `scripts/gen-resources.mjs` turns it
+ * into `index.json` and `SOURCE.json`. This module reads only those generated
+ * files plus the page bodies, so searching is deterministic and needs no model,
+ * network or tokenizer.
+ *
+ * @module dsh-engineering-resources/corpus
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Where the corpus lives, relative to the built module. */
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+let cached;
+/**
+ * Load the index and source pin once per process.
+ *
+ * @returns The corpus.
+ * @throws when the generated files are missing, which means the build did not run.
+ */
+export function corpus() {
+    if (cached !== undefined)
+        return cached;
+    const indexPath = join(ROOT, 'index.json');
+    const sourcePath = join(ROOT, 'SOURCE.json');
+    if (!existsSync(indexPath) || !existsSync(sourcePath)) {
+        throw Object.assign(new Error('The engineering corpus is missing; run `pnpm resources:build` before packing.'), { code: 'RESOURCES_MISSING' });
+    }
+    const index = JSON.parse(readFileSync(indexPath, 'utf8'));
+    const source = JSON.parse(readFileSync(sourcePath, 'utf8'));
+    if (!Array.isArray(index.pages) || index.pages.length === 0) {
+        throw Object.assign(new Error('The engineering corpus is empty; run `pnpm resources:build`.'), { code: 'RESOURCES_MISSING' });
+    }
+    cached = { index, digest: source.digest, directory: ROOT };
+    return cached;
+}
+/**
+ * Read one page body.
+ *
+ * @param id - Page id, as listed by the contents.
+ * @returns Markdown body.
+ */
+export function pageBody(id) {
+    const { index } = corpus();
+    const row = index.pages.find(page => page.id === id);
+    if (row === undefined) {
+        throw Object.assign(new Error(`No resource page named "${id}".`), { code: 'COMPONENT_NOT_FOUND' });
+    }
+    const path = join(ROOT, 'corpus', row.domain, `${row.id}.md`);
+    if (!existsSync(path)) {
+        throw Object.assign(new Error(`The page file for "${id}" is missing from the corpus.`), { code: 'RESOURCES_MISSING' });
+    }
+    // Strip the front matter: the index already carries it, and repeating it in
+    // the answer spends tokens for nothing.
+    return readFileSync(path, 'utf8').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '');
+}
+/** Score one page against a query. Higher is better; zero is no hit. */
+function scoreOf(row, needle) {
+    if (row.id === needle)
+        return 100;
+    if (row.rules.some(rule => rule.toLowerCase() === needle))
+        return 95;
+    if (row.title.toLowerCase() === needle)
+        return 90;
+    if (row.tags.some(tag => tag.toLowerCase() === needle))
+        return 80;
+    if (row.id.includes(needle))
+        return 60;
+    if (row.title.toLowerCase().includes(needle))
+        return 55;
+    if (row.tags.some(tag => tag.toLowerCase().includes(needle)))
+        return 45;
+    if (row.rules.some(rule => rule.toLowerCase().startsWith(needle)))
+        return 40;
+    if (row.domain === needle)
+        return 35;
+    return 0;
+}
+/**
+ * Rank pages by metadata, then by body text for the remainder.
+ *
+ * @param query - Free text, rule id, tag or page id.
+ * @param limit - Most hits to return.
+ * @param domain - Optional domain filter.
+ * @returns Ranked hits, best first.
+ */
+export function search(query, limit = 8, domain) {
+    const { index } = corpus();
+    const needle = query.trim().toLowerCase();
+    const tokens = needle.split(/\s+/u).filter(Boolean);
+    const pool = domain === undefined ? index.pages : index.pages.filter(page => page.domain === domain);
+    const scored = pool
+        .map(row => ({ row, score: tokens.reduce((sum, token) => sum + scoreOf(row, token), 0) }))
+        .filter(hit => hit.score > 0);
+    if (scored.length < limit) {
+        const seen = new Set(scored.map(hit => hit.row.id));
+        for (const row of pool) {
+            if (seen.has(row.id))
+                continue;
+            try {
+                const body = pageBody(row.id).toLowerCase();
+                if (tokens.every(token => body.includes(token)))
+                    scored.push({ row, score: 20 });
+            }
+            catch {
+                // A missing page file is reported when it is read, not during ranking.
+            }
+        }
+    }
+    return scored
+        .sort((left, right) => right.score - left.score || left.row.id.localeCompare(right.row.id))
+        .slice(0, Math.min(Math.max(limit, 1), 20))
+        .map(hit => ({ id: hit.row.id, title: hit.row.title, domain: hit.row.domain, level: hit.row.level, rules: hit.row.rules, score: hit.score }));
+}
+/** Domain order for the contents listing. */
+export const DOMAINS = ['iec', 'rockwell', 'yaskawa', 'view', 'optix', 'craft'];
+/** The contents, grouped by domain, with word counts. */
+export function contents() {
+    const { index } = corpus();
+    return {
+        domains: DOMAINS.filter(domain => index.pages.some(page => page.domain === domain)),
+        pages: index.pages.map(page => ({ id: page.id, title: page.title, domain: page.domain, level: page.level, words: page.words })),
+    };
+}

package/vendor/resources/lib/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The engineering resources row: a local standards corpus, a house-style profile
+ * and the `engineering-standards` skill that tells a model to read both before
+ * authoring.
+ *
+ * The corpus is generated data (`index.json`, `SOURCE.json`) over authored
+ * Markdown; the profile is produced by whichever product package has a project
+ * open. This entry only wires them to the tool registry and, when the host offers
+ * it, to the skills service.
+ *
+ * @module dsh-engineering-resources
+ */
+import type { StyleProfile } from './profile.ts';
+/** Plugin name in a composition. */
+export declare const name = "engineering-resources";
+/** The tools need the registry; the skill is registered when the host offers it. */
+export declare const inject: string[];
+/** The service name a generation tool can inject to read a profile by handle. */
+export declare const PROFILES_SERVICE = "engineeringProfiles";
+/** The skill metadata, kept here so a test can assert it without the file. */
+export declare const SKILL: {
+    name: string;
+    description: string;
+    whenToUse: string;
+};
+/** Configuration for the row. */
+export interface Config {
+    /** Whether the reference and profile tools are registered. Defaults to true. */
+    reference?: boolean;
+}
+/** The service exposed to other rows. */
+export interface ProfilesService {
+    /** The profile for one handle, when it is still in memory. */
+    get(id: string): StyleProfile | undefined;
+}
+/**
+ * Register the resource tools and the standards skill.
+ *
+ * @param ctx - Plugin context with the tool registry and optional services.
+ * @param config - Row configuration.
+ */
+export declare function apply(ctx: {
+    tools: {
+        register(definition: unknown): void;
+    };
+    get?: (name: string) => unknown;
+    provide?: (name: string, value: unknown) => void;
+    logger?: {
+        warn?(message: string): void;
+    };
+}, config?: Config): void;
+export { getProfile } from './store.ts';
+export { validateProfile, profileId } from './profile.ts';
+export type { StyleProfile } from './profile.ts';
+export { resourceTools, referenceTool, profileTool } from './tools.ts';

package/vendor/resources/lib/index.js

@@ -0,0 +1,75 @@
+/**
+ * The engineering resources row: a local standards corpus, a house-style profile
+ * and the `engineering-standards` skill that tells a model to read both before
+ * authoring.
+ *
+ * The corpus is generated data (`index.json`, `SOURCE.json`) over authored
+ * Markdown; the profile is produced by whichever product package has a project
+ * open. This entry only wires them to the tool registry and, when the host offers
+ * it, to the skills service.
+ *
+ * @module dsh-engineering-resources
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resourceTools } from "./tools.js";
+import { getProfile } from "./store.js";
+/** Plugin name in a composition. */
+export const name = 'engineering-resources';
+/** The tools need the registry; the skill is registered when the host offers it. */
+export const inject = ['tools'];
+/** The service name a generation tool can inject to read a profile by handle. */
+export const PROFILES_SERVICE = 'engineeringProfiles';
+/** The skill metadata, kept here so a test can assert it without the file. */
+export const SKILL = {
+    name: 'engineering-standards',
+    description: 'Engineering standards and house style for control code and HMI: read the local corpus for IEC 61131-3, Rockwell, Yaskawa, FactoryTalk and craft rules, profile the open project to follow its own conventions, and cite rule IDs in findings.',
+    whenToUse: 'Before writing or reviewing PLC code, ladder, Structured Text, FactoryTalk View or Optix screens — especially when matching an existing project’s style, or when starting new work that should meet a professional standard.',
+};
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The skill file, in the built package or the source tree. */
+function skillPath() {
+    for (const candidate of [join(HERE, '..', 'SKILL.md'), join(HERE, '..', '..', 'SKILL.md')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Register the resource tools and the standards skill.
+ *
+ * @param ctx - Plugin context with the tool registry and optional services.
+ * @param config - Row configuration.
+ */
+export function apply(ctx, config = {}) {
+    const getService = (service) => (typeof ctx.get === 'function' ? ctx.get(service) : undefined);
+    if (config.reference !== false) {
+        for (const definition of resourceTools(getService))
+            ctx.tools.register(definition);
+    }
+    ctx.provide?.(PROFILES_SERVICE, { get: getProfile });
+    const path = skillPath();
+    const skills = getService('skills');
+    if (path === undefined || skills?.register === undefined) {
+        try {
+            ctx.logger?.warn?.('engineering-resources: the engineering-standards skill was not registered; the tools are available.');
+        }
+        catch {
+            // A logger that refuses must not turn a missing skill into a crash.
+        }
+        return;
+    }
+    const content = readFileSync(path, 'utf8').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/u, '');
+    skills.register({
+        ...SKILL,
+        content,
+        path,
+        source: 'custom',
+        provider: '@aryacode/dsh-engineering',
+        invocation: { modelInvocable: true, userInvocable: true },
+    });
+}
+export { getProfile } from "./store.js";
+export { validateProfile, profileId } from "./profile.js";
+export { resourceTools, referenceTool, profileTool } from "./tools.js";

package/vendor/resources/lib/profile.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The house-style profile: the evidence-backed conventions of one open project.
+ *
+ * A profile is produced by a product package (it owns the parser) and validated
+ * here. It is deliberately small JSON: every field names its evidence and the
+ * whole profile carries a confidence level, because a convention inferred from
+ * six rungs is a hint, not a rule.
+ *
+ * @module dsh-engineering-resources/profile
+ */
+/** One counted convention, e.g. a tag prefix. */
+export interface Counted {
+    /** The observed value. */
+    readonly value: string;
+    /** How many times it was observed. */
+    readonly count: number;
+}
+/** Evidence behind one claim. */
+export interface ProfileEvidence {
+    /** File the evidence came from. */
+    readonly file?: string;
+    /** Rung or line number, when the product can name one. */
+    readonly line?: number;
+    /** How many observations support the claim. */
+    readonly count?: number;
+    /** Human-readable note. */
+    readonly note: string;
+}
+/** Kind of project the profile was read from. */
+export type ProfileKind = 'l5x' | 'ftview' | 'mwi' | 'optix';
+/** The profile schema every product returns. */
+export interface StyleProfile {
+    /** Schema version; refuse anything else. */
+    readonly schema: 1;
+    /** Where the profile came from. */
+    readonly source: {
+        readonly kind: ProfileKind;
+        readonly path: string;
+        readonly sha256?: string;
+    };
+    /** Naming conventions, when the product can infer them. */
+    readonly naming?: {
+        readonly tags?: {
+            readonly prefixes: readonly Counted[];
+            readonly case?: string;
+        };
+        readonly routines?: {
+            readonly case?: string;
+            readonly examples?: readonly string[];
+        };
+        readonly displays?: {
+            readonly case?: string;
+            readonly examples?: readonly string[];
+        };
+    };
+    /** Logic idioms the project actually uses. */
+    readonly idioms?: {
+        readonly sealIn?: {
+            readonly count: number;
+            readonly form: string;
+        };
+        readonly latch?: {
+            readonly count: number;
+        };
+        readonly stateMachine?: {
+            readonly count: number;
+            readonly form: string;
+        };
+    };
+    /** HMI conventions, for FactoryTalk View and Optix. */
+    readonly hmi?: {
+        readonly palette?: readonly Counted[];
+        readonly fonts?: readonly Counted[];
+        readonly button?: readonly Counted[];
+        readonly navigation?: {
+            readonly displaysWithNav: number;
+            readonly displays: number;
+        };
+        readonly popups?: {
+            readonly onTop: number;
+            readonly replace: number;
+        };
+    };
+    /** Comment density, where the product exposes comments. */
+    readonly comments?: {
+        readonly total: number;
+        readonly commented: number;
+        readonly ratio: number;
+    };
+    /** What the profile is based on. */
+    readonly evidence: readonly ProfileEvidence[];
+    /** How much to trust it. */
+    readonly confidence: 'low' | 'medium' | 'high';
+}
+/** A validation result: the profile, or the reasons it was refused. */
+export interface ProfileCheck {
+    readonly ok: boolean;
+    readonly problems: readonly string[];
+}
+/**
+ * Validate one profile from a product package.
+ *
+ * @param value - Whatever the product returned.
+ * @returns Ok, or the specific problems.
+ */
+export declare function validateProfile(value: unknown): ProfileCheck;
+/**
+ * A stable handle for one profile, so a tool can refer to it later.
+ *
+ * @param profile - A validated profile.
+ * @returns Short id derived from the source and its digest.
+ */
+export declare function profileId(profile: StyleProfile): string;

package/vendor/resources/lib/profile.js

@@ -0,0 +1,52 @@
+/**
+ * The house-style profile: the evidence-backed conventions of one open project.
+ *
+ * A profile is produced by a product package (it owns the parser) and validated
+ * here. It is deliberately small JSON: every field names its evidence and the
+ * whole profile carries a confidence level, because a convention inferred from
+ * six rungs is a hint, not a rule.
+ *
+ * @module dsh-engineering-resources/profile
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Validate one profile from a product package.
+ *
+ * @param value - Whatever the product returned.
+ * @returns Ok, or the specific problems.
+ */
+export function validateProfile(value) {
+    const problems = [];
+    if (typeof value !== 'object' || value === null)
+        return { ok: false, problems: ['profile is not an object'] };
+    const profile = value;
+    if (profile.schema !== 1)
+        problems.push('schema must be 1');
+    const source = profile.source;
+    if (source === undefined)
+        problems.push('source is required');
+    else {
+        if (!['l5x', 'ftview', 'mwi', 'optix'].includes(source.kind))
+            problems.push(`unknown source.kind ${JSON.stringify(source.kind)}`);
+        if (typeof source.path !== 'string' || source.path === '')
+            problems.push('source.path is required');
+    }
+    if (!['low', 'medium', 'high'].includes(profile.confidence ?? ''))
+        problems.push('confidence must be low, medium or high');
+    if (!Array.isArray(profile.evidence) || profile.evidence.length === 0)
+        problems.push('evidence must be a non-empty array');
+    if (profile.naming === undefined && profile.idioms === undefined && profile.hmi === undefined && profile.comments === undefined) {
+        problems.push('a profile needs at least one of naming, idioms, hmi or comments');
+    }
+    return { ok: problems.length === 0, problems };
+}
+/**
+ * A stable handle for one profile, so a tool can refer to it later.
+ *
+ * @param profile - A validated profile.
+ * @returns Short id derived from the source and its digest.
+ */
+export function profileId(profile) {
+    const seed = JSON.stringify([profile.source.kind, profile.source.path, profile.source.sha256 ?? '', profile.evidence.length]);
+    return createHash('sha256').update(seed).digest('hex').slice(0, 12);
+}

package/vendor/resources/lib/store.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Chat-scoped storage for house-style profiles.
+ *
+ * A profile is produced by a product tool call and consumed by a generation tool
+ * later in the same conversation, so it lives in memory under a short handle. It
+ * is rebuilt from the project whenever the agent asks again; nothing is written
+ * to disk.
+ *
+ * @module dsh-engineering-resources/store
+ */
+import type { StyleProfile } from './profile.ts';
+/**
+ * Remember one profile under its handle.
+ *
+ * @param id - Handle from `profileId`.
+ * @param profile - The validated profile.
+ */
+export declare function rememberProfile(id: string, profile: StyleProfile): void;
+/** The profile for one handle, when it is still in memory. */
+export declare function getProfile(id: string): StyleProfile | undefined;
+/** Drop every profile; tests use this between cases. */
+export declare function clearProfiles(): void;

package/vendor/resources/lib/store.js

@@ -0,0 +1,35 @@
+/**
+ * Chat-scoped storage for house-style profiles.
+ *
+ * A profile is produced by a product tool call and consumed by a generation tool
+ * later in the same conversation, so it lives in memory under a short handle. It
+ * is rebuilt from the project whenever the agent asks again; nothing is written
+ * to disk.
+ *
+ * @module dsh-engineering-resources/store
+ */
+/** Most profiles one process keeps before dropping the oldest. */
+const MAX = 32;
+const profiles = new Map();
+/**
+ * Remember one profile under its handle.
+ *
+ * @param id - Handle from `profileId`.
+ * @param profile - The validated profile.
+ */
+export function rememberProfile(id, profile) {
+    if (profiles.size >= MAX) {
+        const oldest = profiles.keys().next().value;
+        if (oldest !== undefined)
+            profiles.delete(oldest);
+    }
+    profiles.set(id, profile);
+}
+/** The profile for one handle, when it is still in memory. */
+export function getProfile(id) {
+    return profiles.get(id);
+}
+/** Drop every profile; tests use this between cases. */
+export function clearProfiles() {
+    profiles.clear();
+}