Skip to main content

Test and deploy

Treat the manifest and its executable test suite as one release artifact.

Define the contract​

import {defineToolTests} from '@twl-tool/app-sdk';
import app from './twl-tool.app.js';

export default defineToolTests({
  tool: app,
  scenarios: [{
    name: 'composes a custom page and native writing surfaces',
    source: {
      environment: 'fixture',
      title: 'Write a Social Post',
      slug: 'write-a-social-post',
      status: 'active',
    },
    permissions: ['documents.write', 'workflows.execute', 'ai-chat.use'],
    workflow: {
      key: 'writePost',
      slug: 'write-a-social-post',
      desiredState: 'active',
      triggerTypes: ['manual'],
      steps: ['content.generate-written-content@1', 'documents.create-document@1'],
    },
  }],
});

Run and certify​

npx twl-tool test twl-tool.tool.test.ts
npx twl-tool certify twl-tool.tool.test.ts --out certification.json

Certification is bound to the manifest checksum. Change the app configuration and the suite must pass again before that version is installable from a managed catalog.

Validate, plan, deploy​

npx twl-tool validate twl-tool.app.ts --url https://twl-tool.example
npx twl-tool plan twl-tool.app.ts --url https://twl-tool.example --organization acme
npx twl-tool deploy twl-tool.app.ts --url https://twl-tool.example --organization acme

In-place upgrades are non-destructive by default:

  • omitted resources are retained
  • additive columns and safe labels can be applied
  • column type, default, and nullability changes are blocked until an explicit migration system handles them

Always review the plan and deploy the exact fingerprint it returns.