Skip to content

Development and Packaging

Sceleratis edited this page Oct 20, 2026 · 1 revision

Development and packaging

The repository contains a VS Code extension, maintained language/checker sources, and a portable agent package. They share a format but have separate installation paths.

Work from the main repository

git clone https://github.com/Sceleratis/PlainLogic-Language.git
cd PlainLogic-Language
npm ci --ignore-scripts

Use Node.js 22 or later for the development dependencies and VSIX builder. The repository's agent resource/export tools use Python's standard library. The installed editor extension itself has no third-party runtime dependencies and does not invoke Python.

Repository map

Path Purpose
docs/plainlogic.md, docs/extensibility.md Maintained language and extension-surface rules.
tools/check_plainlogic.py Maintained optional canonical checker.
examples/ Maintained example inputs.
src/language.js Non-executing editor analysis and lexical symbol index.
src/extension.js, src/features.js VS Code provider adapters and editing helpers.
syntaxes/, snippets/, language-configuration.json TextMate grammar, snippets, and editor configuration.
skills/plainlogic/SKILL.md and workflow references Maintained agent instructions.
plugin.json Portable Agent Plugins identity and presentation metadata.
.codex-plugin/, .claude-plugin/, .agents/plugins/ Client compatibility manifests and local catalogs.
tools/package_agents.py Resource synchronization and reproducible ZIP export.
test/ Editor, grammar, checker, package, and host integration checks.

Language/checker/example copies under skills/plainlogic/ are generated resources. Workflow references such as validation.md and conversion.md are maintained instructions, not generated language copies.

Synchronize and verify

For the full repository checks, including agent resources:

npm run agents:sync
npm run agents:check
npm test
npm run test:checker
npm run test:agent-build

Synchronization writes only the known generated resources. The check form detects drift without refreshing them.

The Node suite includes real TextMate/Oniguruma grammar checks, editor indexing/provider helpers, manifest/path invariants, and generated-resource consistency. The Python suites cover canonical grammar and portable export invariants. Neither suite treats PlainLogic cases as an execution engine.

Test in VS Code

npm run test:integration

The launcher uses an installed VS Code executable and creates an isolated profile, extension directory, and report under .vscode-test/. It does not download VS Code or install the extension into the normal profile. Set VSCODE_EXECUTABLE to the executable's absolute path if automatic lookup cannot find it.

To load the source manually:

code --extensionDevelopmentPath="<absolute-path-to-PlainLogic-Language>"

Editor launch settings are local and ignored by Git; a committed .vscode folder is not required.

Build the editor package

npm run package

At version 0.3.0 this creates dist/plainlogic-0.3.0.vsix. The prepackage script creates dist/ first. The VSIX excludes development dependencies, test profiles, agent plugin metadata, and the standalone skill tree. See VS Code installation.

Build the agent packages

npm run package:agents

This synchronizes resources, checks contained skill references, and writes:

  • dist/plainlogic-agents-0.3.0.zip: portable root manifest, Codex/Claude compatibility metadata and catalogs, installation guide, and the complete skill.
  • dist/plainlogic-skill-0.3.0.zip: standalone plainlogic/ folder with instructions, references, checker, examples, and optional Codex UI metadata.

The ZIPs use sorted entries and fixed timestamps for reproducible exports. Bundled resource paths must resolve within their package/skill root. No original developer checkout or node_modules is needed to read the installed skill. Builds do not register marketplaces, enable plugins, or publish artifacts.

To check Claude manifests without installing:

claude plugin validate ./.claude-plugin/plugin.json
claude plugin validate ./.claude-plugin/marketplace.json

The documented commands are supported by the locally verified Claude Code 2.1.118. Check the installed client's help before relying on additional validation flags. See the plugin pages for installing and invoking the workflow.

Maintain the wiki

The wiki is a separate Git repository:

git clone https://github.com/Sceleratis/PlainLogic-Language.wiki.git

Markdown filenames determine page slugs. _Sidebar.md and _Footer.md provide shared navigation. When updating behavior, verify claims against source and focused tests, validate complete canonical examples with the checker, and keep fragments clearly labelled. A native example passing the PlainLogic checker has not been compiled in its target language.

The wiki and code repositories have separate histories. Local wiki edits become live when the wiki's default branch is pushed; editing code-repository docs alone does not update wiki pages. See GitHub's wiki workflow and sidebar/footer conventions.

Sources: package scripts, export builder, host launcher, and VSIX exclusions.

Clone this wiki locally