Tooling and Validation

Use this guide after completing Workspace Getting Started. Use it when you change tests, tasks, triggers, Trends definitions, or sanitizers: check the files in your editor, validate them, and make sure the next run uses your changes.

Tests, tasks, and triggers are ordinary source-controlled files. Ansight supplies schemas, TypeScript declarations, and CLI checks to catch missing fields, unsupported settings, and type errors before the automation runs.

Generated tooling

Workspace initialization creates the support files used by editors and local or CI checks:

ansight/
  package.json
  tasks/
    ansight-task.js
    ansight-task.d.ts
    tsconfig.json
  tests/
  trends/
  sanitizers/
    ansight-sanitizer.d.ts
    tsconfig.json
  triggers/
    ansight-trigger.d.ts
    tsconfig.json
  schema/
    task-definition.v1.schema.json
    test-definition.v1.schema.json
    trends-definition.v1.schema.json
    trigger-definition.v1.schema.json

Review the generated task declarations, trigger declarations, sanitizer declarations, and JSON schemas online with syntax highlighting and downloads.

Initialization is idempotent. Customized support files are preserved. Use --force only when you intend to replace them with the canonical files from the installed Ansight host.

The generated package.json sets "type": "module", so plain .ts files use ES module semantics for execution and TypeScript tooling. Each definition directory also includes an editable README.md with a starter example and its important constraints.

Transfer an existing workspace

Use a workspace ZIP to move definitions and their supporting files together:

ansight workspace export --app-id com.example.app --output workspace.zip
ansight workspace import workspace.zip ./another-project
ansight test validate ./another-project

Export also accepts a repository path in place of --app-id. Import preserves files absent from the ZIP and requires --force to replace conflicting files. It does not run definitions or register the destination. Review imported code and run the applicable TypeScript checks below before linking it to an app. See Export and import a workspace ZIP for archive limits, exclusions, overwrite behavior, and app registration.

IDs and paths

Definition IDs come from paths beneath their respective directories:

Within ansight/tasks, only .ts files with an exported static task descriptor receive an ID. Descriptor-free .ts files and .d.ts files are support modules that task code can import.

CLI-created test and task IDs can contain letters, numbers, dots, hyphens, and underscores and are limited to 160 characters. Trigger IDs use the same characters and are limited to 120 characters. Start and end a CLI-created ID with a letter or number and avoid consecutive dots.

Prefer stable, domain-oriented IDs. Renaming or moving a definition changes its path-derived identity and can break prompts, scripts, or saved references.

Review in the local player

The local player’s Tests area groups discovered definitions by app:

• ansight/tests contains agentic YAML scenarios.
• ansight/tasks contains explicitly invoked deterministic modules.
• ansight/triggers contains event-driven modules.

Select a workspace app and review the discovered definitions. Author and save the source files in your repository editor; the host validates test YAML and the static task or trigger module shape during discovery. Repository tasks can be tested against an exact open simulator session through the CLI.

The host also monitors ordinary sessions automatically after an app is linked to its trusted codebase with ansight app register <app-id> --codebase <path>. On session finalization it evaluates definitions whose windows were observed in that session. The served local explorer’s Trends view browses current and baseline values across registered apps and app versions.

For a full TypeScript editing experience, open the repository in an external editor such as Visual Studio Code.

Static task and trigger descriptors

Every task and trigger module contains one statically extractable descriptor:

export const task = {
  "schemaVersion": 1,
  "title": "Verify home",
  "description": "Checks the signed-in home state."
};

export const trigger = {
  "schemaVersion": 1,
  "eventKind": "app.event"
};

Keep descriptors as JSON-compatible object literals with double-quoted keys and values. Do not use variables, spreads, functions, template substitutions, or computed properties inside a descriptor. The host reads the descriptor without importing or executing the module.

An invalid task produces a warning while other valid tasks remain discoverable. An invalid trigger rejects that repository’s trigger catalog, so validate every trigger before connecting it.

Visual Studio Code completion and checking

VS Code provides completion and diagnostics through its built-in TypeScript language service. The generated tsconfig.json makes each module directory a strict, no-emit TypeScript project compatible with the CLI:

{
  "compilerOptions": {
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "target": "ES2022",
    "strict": true
  },
  "include": [
    "*.ts",
    "*.d.ts",
    "**/*.ts",
    "**/*.d.ts"
  ]
}

Import the canonical declaration with import type, constrain the descriptor with satisfies, and type the default function’s invocation parameter.

Task module:

import type { TaskDefinition, TaskInvocation } from "./ansight-task.d.ts";

type ValidateAreaInput = { area: string };

export const task = {
  "schemaVersion": 1,
  "title": "Validate area",
  "description": "Validates one named map area."
} satisfies TaskDefinition;

export default async function validateArea(
  { input, ansight, expect }: TaskInvocation<ValidateAreaInput>
) {
  // VS Code completes input, ansight, and expect here.
}

Trigger module:

import type {
  TriggerContext,
  TriggerDefinition
} from "./ansight-trigger.d.ts";

type ErrorPayload = { message: string };

export const trigger = {
  "schemaVersion": 1,
  "eventKind": "session.log.received"
} satisfies TriggerDefinition;

export default async function captureError(
  { event, app }: TriggerContext<ErrorPayload>
) {
  // VS Code completes event and app here.
}

Adjust the import when the module is nested. For example, ansight/tasks/map/validate-area.ts normally imports ../ansight-task.d.ts.

If a file is not receiving project diagnostics, run TypeScript: Go to Project Configuration in VS Code and confirm that it resolves to the expected tsconfig.json. Restart the TypeScript language server after replacing a declaration file if its old shape remains cached.

Are the declaration files required at runtime?

No. Declaration files, tsconfig.json, and import type statements support editors and type checking. The CLI does not require them to run a module.

The declarations must be resolvable somewhere for completion to work. The current workspace initializer copies them locally so .NET, Swift, Kotlin, Flutter, and other repositories get offline editor support without requiring a JavaScript package manager. A repository that supplies the same contract from a dependency can import that dependency instead and omit the local declaration copy.

The local declarations have one additional benefit: they come from the installed host and therefore match its exact contract. Keep dependency-provided contracts aligned with the host version that will load the modules.

ESLint is optional and separate

tsc catches type errors, invalid contract properties, implicit any, and incorrect function usage. ESLint adds rule-based checks such as unused variables and consistency rules.

For an npm-enabled repository, install ESLint and the VS Code ESLint extension:

npm install --save-dev eslint @eslint/js globals typescript-eslint

An eslint.config.mjs scoped to Ansight modules can start with:

import js from "@eslint/js";
import globals from "globals";
import tseslint from "typescript-eslint";

export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ["ansight/{tasks,triggers,sanitizers}/**/*.ts"],
    languageOptions: {
      globals: globals.node
    }
  }
);

ESLint is not required for host discovery or execution.

Validate locally and in CI

Check test and Trends definitions for invalid fields or references:

ansight test validate .

Install TypeScript as a development dependency when the repository does not already provide tsc, then type-check all three projects:

npm install --save-dev typescript
npx tsc -p ansight/tasks/tsconfig.json
npx tsc -p ansight/triggers/tsconfig.json
npx tsc -p ansight/sanitizers/tsconfig.json

Inspect the host’s task and trigger catalogs without executing code:

ansight task list --app-id com.example.app --repository .
ansight repo automation inspect com.example.app .

The CLI does not type-check TypeScript modules before execution. Run the matching local or CI type check for .ts modules.

Refresh discovery

Saving a file does not reload every part of the workspace. In particular, connected triggers keep the event-matching rules loaded when you connected them. Check and reload those rules after editing a trigger, even if its TypeScript function has not changed.

From the repository root, with the resident host running:

ansight repo automation inspect com.example.app .

Review the reported triggers and fix any warnings. Inspection validates the saved definitions; it does not activate them or replace the connected rules. When they are ready to run, reconnect and verify the active connection:

ansight repo automation connect com.example.app .
ansight repo automation list --json

Starting another app session does not reload the connected trigger rules. Use the matching check for other workspace changes:

See session lifecycle for how the host loads definitions and restores linked trigger connections.

Optional checked-in schemas can support repository-specific validation, but the running Ansight host remains the source of truth.

Common problems

Related docs

• Workspace Getting Started
• Tests
• Tasks
• Triggers
• Schemas