deveco-harness 0.1.0

package/skills/arkts-error-fixes/reference/window_type_errors.md

@@ -0,0 +1,95 @@
+# Window API Type Errors
+
+## Error: `window.getLastWindow` type inference issue
+
+### Error Message
+```
+Type 'void & Promise<Window>' errors
+```
+
+### Cause
+Using async/await pattern with `window.getLastWindow()` causes type inference issues in ArkTS. The function signature doesn't properly resolve to a Promise type when used with await.
+
+### Solution
+Use the callback pattern instead of async/await for `window.getLastWindow()`.
+
+### Key Points
+- Use callback pattern: `window.getLastWindow(context, (err, win) => { ... })`
+- Always check error code: `if (err.code !== 0)`
+- Handle errors gracefully with console logging
+- Use explicit type annotation for size: `(size: window.Size) => void`
+
+### Callback Pattern
+```typescript
+window.getLastWindow(context, (err, win) => {
+  if (err.code !== 0) {
+    console.error('Failed to get window:', err);
+    return;
+  }
+  
+  // Use window instance
+  const properties = win.getWindowProperties();
+});
+```
+
+### Window Properties
+```typescript
+interface WindowProperties {
+  windowRect: Rect;      // Window position and size
+  type: WindowType;        // Window type
+  mode: WindowMode;         // Window mode
+  brightness: number;       // Brightness (0.0-1.0)
+  isPrivacyMode: boolean;   // Privacy mode status
+  isFullScreen: boolean;    // Full screen status
+  layoutMode: LayoutMode;   // Layout mode
+}
+
+interface Rect {
+  left: number;   // Left position
+  top: number;    // Top position
+  width: number;  // Width
+  height: number; // Height
+}
+```
+
+### Window Size Change Event
+```typescript
+win.on('windowSizeChange', (size: window.Size) => {
+  console.info(`New size: ${size.width}x${size.height}`);
+});
+
+interface Size {
+  width: number;  // New width
+  height: number; // New height
+}
+```
+
+### Common Window Events
+```typescript
+win.on('windowSizeChange', (size: window.Size) => { });
+win.on('systemBarTintChange', (region: Region) => { });
+win.on('windowEvent', (data: WindowEvent) => { });
+win.on('avoidAreaChange', (data: AvoidArea) => { });
+```
+
+### Error Handling
+```typescript
+// Check for specific error codes
+if (err.code === 1300001) {
+  // Invalid parameter
+} else if (err.code === 1300002) {
+  // Window not found
+} else if (err.code === 1300003) {
+  // Window operation failed
+}
+```
+
+### Best Practices
+1. **Always check error code**: Never assume success
+2. **Log errors**: Use console.error for debugging
+3. **Clean up listeners**: Remove event listeners in `aboutToDisappear()`
+4. **Use type annotations**: Explicit types prevent inference issues
+5. **Handle window state**: Account for window resize and orientation changes
+
+### Related Files
+- [Code Example](../assets/WindowTypeError.ets)

package/skills/arkts-grammar-standards/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: arkts-grammar-standards
+description: Load this skill when writing or modifying .ets files. Use it for ArkTS syntax rules, ArkTS-specific restrictions, TypeScript-to-ArkTS syntax differences, syntax compliance review, and ArkTS syntax questions.
+---
+
+# arkts-grammar-standards
+
+Use this skill before authoring ArkTS code and to answer ArkTS syntax and restriction questions with grounded references.
+
+## Core authoring checklist
+
+Before writing or modifying `.ets` files:
+
+- Treat the code as ArkTS, not generic TypeScript.
+- Do not use `any` or `unknown` unless the user explicitly allows it.
+- Do not use `as` type assertions; use explicit types, constructors, or typed helper functions.
+- Do not rely on structural typing; prefer named classes, interfaces, and explicit `implements` relationships.
+- Do not use dynamic property access such as `obj[key]` as a normal modeling pattern; prefer direct property access with known names.
+- Give object literals explicit type context through typed variables, typed parameters, or class/interface construction.
+- Do not use inline object literal types; define a named interface or class instead.
+- Do not use template literals such as `` `${value}` ``; use string concatenation and explicit conversion.
+- Do not use namespaces as runtime values; import or reference the concrete exported value/type that is needed.
+- Avoid restricted TypeScript patterns such as destructuring declarations, destructuring parameters, function expressions, nested local function declarations, class expressions, `delete`, `in`, `for...in`, and type queries like `typeof Foo`.
+
+Prefer the bundled reference files over model memory. Keep the answer focused on:
+
+- whether a syntax form is allowed
+- what ArkTS expects instead
+- whether the rule comes from the language guide or from the linter-derived summary
+- which topic best matches the user's code or question
+
+## Reference order
+
+Read these files as needed:
+
+1. `references/topic-aliases.json`
+2. `references/basic-syntax.md`
+3. `references/restrictions.md`
+4. `references/ts-diff.md`
+
+Use `basic-syntax.md` for normal ArkTS writing patterns.
+Use `restrictions.md` when the question is about forbidden syntax, restricted operators, object literal rules, `Sendable`, or review comments.
+Use `ts-diff.md` when the user is porting TypeScript or asking why a familiar TypeScript pattern does not work in ArkTS.
+
+## Source rules
+
+- Treat `basic-syntax.md` and `ts-diff.md` as guide-oriented summaries backed by the bundled ArkTS language guide sections.
+- Treat `restrictions.md` as implementation-derived guidance based on the linter summary. Say that clearly when citing it.
+- Do not present linter-derived restrictions as if they were verbatim official spec text.
+- If both a guide-oriented explanation and a linter restriction apply, mention both and explain the relationship in one or two sentences.
+
+## Response shape
+
+Use this format unless the user asks for something else:
+
+```markdown
+- Topic: <short topic>
+- Source: <guide-summary | linter-summary | ts-diff-summary>
+- Reference: <reference file and section>
+- Why it matches: <one sentence>
+- Guidance: <one or two sentences>
+```
+
+If the user shows code, add a short rewrite suggestion after the guidance.
+
+## Working rules
+
+- Prefer direct syntax guidance over broad language tutorials.
+- Prefer named ArkTS alternatives such as class, interface, explicit field type, arrow function, or direct property access.
+- Keep citations short and traceable.
+- Do not expand the answer into build, run, debug, or tool workflows unless the user explicitly asks for that after the syntax answer.

package/skills/arkts-grammar-standards/references/basic-syntax.md

@@ -0,0 +1,103 @@
+# ArkTS Basic Syntax
+
+This file summarizes high-value ArkTS syntax guidance for common authoring and review questions.
+
+## Variables
+
+- Use `let` or `const` for variable declarations.
+- Prefer `const` when the binding does not change.
+- Keep types explicit when inference would be unclear.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/*`
+- Linter summary: declaration section and `arkts-no-var`
+
+## Classes
+
+- Prefer named `class` declarations.
+- Declare fields in the class body.
+- Use constructors to establish valid state.
+- Prefer constructing instances with `new` instead of treating classes as loose object shapes.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/classes.md`
+
+## Interfaces
+
+- Use named interfaces for reusable contracts.
+- Prefer interface or class names over inline object type declarations.
+- Use `implements` to make class contracts explicit.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/interfaces.md`
+
+## Functions
+
+- Prefer arrow functions for function values.
+- Keep return types explicit when the result is not obvious.
+- Use top-level or class methods for reusable logic instead of nested local function declarations.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/functions.md`
+- Linter summary: function declaration section
+
+## Operators
+
+- Use normal arithmetic, comparison, logical, and conditional operators with explicit types.
+- Prefer `===` and `!==`.
+- Use explicit conversions instead of JavaScript-style coercion.
+- Use string concatenation and explicit conversion instead of template literals.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/advanced-operators.md`
+
+## Strings
+
+- Use ordinary string literals and concatenation for formatted text.
+- Convert non-string values explicitly before concatenating when the target expects a string.
+- Avoid template literal syntax such as `` `Count: ${count}` ``.
+
+ArkTS style:
+
+```ts
+const label: string = "Count: " + count.toString()
+```
+
+Reference:
+- Linter summary: syntax restriction section
+
+## Object modeling
+
+- Prefer named classes and interfaces for stable data models.
+- Use object literals only when there is clear explicit type context.
+- Prefer direct property access with known names.
+- Avoid `Record<string, T>` and dynamic keys when a named interface or class can model the shape.
+
+ArkTS style:
+
+```ts
+interface UserLabels {
+  name: string
+  title: string
+}
+
+const labels: UserLabels = {
+  name: "Name",
+  title: "Title",
+}
+const title: string = labels.title
+```
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/classes.md`
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/interfaces.md`
+- Linter summary: object literal section
+
+## Namespaces and imports
+
+- Treat namespaces as declaration or type organization, not runtime objects to pass around.
+- Import or reference the concrete exported class, enum, function, or type that the code needs.
+- If a namespace-like module is needed at runtime, model the runtime value with an explicit class or exported object that ArkTS accepts.
+
+Reference:
+- Linter summary: namespace section

package/skills/arkts-grammar-standards/references/restrictions.md

@@ -0,0 +1,100 @@
+# ArkTS Restrictions
+
+This file summarizes ArkTS-specific restrictions that are especially useful in code review and syntax troubleshooting.
+
+Unless noted otherwise, the rules below are derived from the bundled linter summary rather than copied from the official guide text.
+
+## Declarations
+
+- Do not use `var`; use `let` or `const`.
+- Do not use destructuring in variable declarations.
+- Do not use destructuring in parameters.
+- Do not rely on `any` or `unknown`.
+- Do not use `as` type assertions as a shortcut around ArkTS type checking.
+- Avoid definite assignment assertions like `!`; in `Sendable` classes they are not allowed.
+
+Reference:
+- Linter summary: declaration section
+- Rules: `arkts-no-var`, `arkts-no-destruct-decls`, `arkts-no-destruct-params`, `arkts-no-any-unknown`, `arkts-no-definite-assignment`
+- Project authoring rule: avoid `as` type assertions unless explicitly requested.
+
+## Functions and classes
+
+- Do not use nested local function declarations.
+- Do not use function expressions; prefer arrow functions.
+- Do not use generator functions or `yield`.
+- Do not use class expressions.
+- Do not use standalone `this` in free functions.
+
+Reference:
+- Linter summary: function and class sections
+- Rules: `arkts-no-nested-funcs`, `arkts-no-func-expressions`, `arkts-no-generators`, `arkts-no-class-literals`, `arkts-no-standalone-this`
+
+## Object and property access
+
+- Do not treat object literals as free-form structural types.
+- Do not declare inline object literal types in place of named interfaces or classes.
+- Object literals must have explicit type context, such as a typed variable, typed parameter, or declared class/interface target.
+- Do not depend on dynamic property access as a normal modeling pattern.
+- Avoid `Record<string, T>` when it encourages dynamic indexing; define a named type with known properties instead.
+- Prefer identifier property names and direct dot access.
+
+Reference:
+- Linter summary: object literal and property access sections
+- Rules: `arkts-no-structural-typing`, `arkts-no-untyped-obj-literals`, `arkts-no-obj-literals-as-types`, `arkts-no-props-by-index`, `arkts-identifiers-as-prop-names`
+
+## String syntax
+
+- Template literals are not supported for ArkTS authoring in this project.
+- Rewrite interpolation to string concatenation with explicit conversion.
+
+Example rewrite:
+
+```ts
+const label: string = "Likes: " + likeCount.toString()
+```
+
+Reference:
+- Linter summary: syntax restriction section
+
+## Namespaces
+
+- Do not use a namespace itself as a runtime value.
+- Avoid namespace bodies that contain runtime statements; keep namespace-like organization to supported declarations.
+- Prefer importing concrete exported symbols or defining explicit runtime classes/objects.
+
+Reference:
+- Linter summary: namespace section
+- Rules: `arkts-no-ns-statements`
+
+## Restricted operators and statements
+
+- `delete` is not supported.
+- `in` and `for...in` are restricted.
+- `typeof` is allowed in expression context, but not as a type query.
+- `catch` clauses must not carry an explicit exception type annotation.
+- Destructuring assignment is not supported.
+
+Reference:
+- Linter summary: operators and statements sections
+- Rules: `arkts-no-delete`, `arkts-no-in`, `arkts-no-types-in-catch`, `arkts-no-destruct-assignment`, `arkts-no-type-query`
+
+## Sendable-focused restrictions
+
+- `Sendable` classes must use explicit field types.
+- `Sendable` field types must themselves be sendable.
+- `Sendable` types must not be initialized directly from object literals or array literals.
+- `Sendable` classes and functions have stricter capture and inheritance rules.
+
+Reference:
+- Linter summary: sendable sections
+- Rules: `arkts-sendable-explicit-field-type`, `arkts-sendable-prop-types`, `arkts-sendable-obj-init`, `arkts-sendable-class-inheritance`
+
+## How to cite this file
+
+When using this file in an answer, say that the restriction comes from the linter-derived ArkTS summary.
+Use that wording especially for:
+
+- forbidden syntax claims
+- `Sendable` restrictions
+- dynamic object model limitations

package/skills/arkts-grammar-standards/references/topic-aliases.json

@@ -0,0 +1,93 @@
+{
+  "variables": [
+    "var",
+    "let",
+    "const",
+    "变量",
+    "变量声明"
+  ],
+  "destructuring": [
+    "destructuring",
+    "destructure",
+    "解构",
+    "解构赋值",
+    "解构参数"
+  ],
+  "functions": [
+    "arrow function",
+    "function expression",
+    "nested function",
+    "generator",
+    "函数表达式",
+    "箭头函数",
+    "局部函数"
+  ],
+  "classes": [
+    "class",
+    "class expression",
+    "constructor",
+    "类",
+    "构造函数"
+  ],
+  "interfaces": [
+    "interface",
+    "inline object type",
+    "structural typing",
+    "接口",
+    "结构类型"
+  ],
+  "operators": [
+    "delete",
+    "typeof",
+    "in operator",
+    "for in",
+    "catch",
+    "as",
+    "type assertion",
+    "as const",
+    "运算符",
+    "类型查询",
+    "类型断言"
+  ],
+  "object-literal": [
+    "object literal",
+    "dynamic property",
+    "indexed access",
+    "record",
+    "Record",
+    "property by index",
+    "对象字面量",
+    "动态属性",
+    "动态索引"
+  ],
+  "strings": [
+    "template literal",
+    "template string",
+    "${",
+    "string interpolation",
+    "模板字符串",
+    "字符串插值"
+  ],
+  "namespace": [
+    "namespace",
+    "namespace as value",
+    "Cannot use namespace as a value",
+    "命名空间",
+    "namespace 作为值"
+  ],
+  "sendable": [
+    "sendable",
+    "@sendable",
+    "可发送",
+    "并发类型"
+  ],
+  "typescript-diff": [
+    "typescript",
+    "ts",
+    "migration",
+    "difference",
+    "改写",
+    "迁移",
+    "差异"
+  ]
+}

package/skills/arkts-grammar-standards/references/ts-diff.md

@@ -0,0 +1,108 @@
+# TypeScript to ArkTS Syntax Differences
+
+This file highlights TypeScript patterns that often need rewriting in ArkTS.
+
+## Dynamic JavaScript patterns are narrower
+
+- ArkTS is not a drop-in TypeScript superset in practice.
+- Patterns that depend on dynamic object mutation, loose shape matching, or reflective syntax are often rejected.
+- Patterns based on `Record<string, T>`, arbitrary indexes, or namespace objects often need explicit ArkTS models.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/09-Migration-Guide/01-TypeScript-to-ArkTS/typescript-to-arkts-migration-guide.md`
+- Linter summary: overview section
+
+## Prefer named types over inline shapes
+
+TypeScript style:
+
+```ts
+function printPoint(point: { x: number; y: number }): void {}
+```
+
+ArkTS style:
+
+```ts
+interface PointLike {
+  x: number
+  y: number
+}
+
+function printPoint(point: PointLike): void {}
+```
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/interfaces.md`
+
+## Prefer declarations over expressions
+
+- Rewrite function expressions to arrow functions when the function is used as a value.
+- Rewrite class expressions to named class declarations.
+- Move nested function declarations to top-level declarations, class methods, or arrow-function values.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/classes.md`
+- Linter summary: function and class sections
+
+## Prefer explicit class and interface modeling
+
+- TypeScript often treats classes as object shapes; ArkTS prefers constructor-based initialization and declared members.
+- TypeScript often relies on structural typing; ArkTS narrows that style and expects explicit named contracts.
+- TypeScript often uses `Record` or indexed access for flexible maps; ArkTS authoring should prefer named interfaces/classes and direct property access when property names are known.
+
+Reference:
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/classes.md`
+- Guide: `docs/ArkTS-Language-Guide/02-Basic-Syntax/interfaces.md`
+- Linter summary: structural typing restriction
+
+## Rewrite template strings
+
+TypeScript style:
+
+```ts
+const label: string = `Count: ${count}`
+```
+
+ArkTS style:
+
+```ts
+const label: string = "Count: " + count.toString()
+```
+
+Reference:
+- Linter summary: syntax restriction section
+
+## Rewrite namespace-as-value patterns
+
+TypeScript style:
+
+```ts
+const api = common
+api.doWork()
+```
+
+ArkTS style:
+
+```ts
+common.doWork()
+```
+
+If the code needs a runtime object, define that object explicitly instead of using a namespace as the value.
+
+Reference:
+- Linter summary: namespace section
+
+## Remove unsupported or narrowed syntax
+
+Common rewrites:
+
+- `var` -> `let` or `const`
+- destructuring declaration -> explicit local bindings
+- `value as T` -> typed variable, typed function return, constructor, or explicit conversion
+- `` `${value}` `` -> string concatenation with explicit conversion
+- `delete obj.x` -> construct the desired value without runtime property deletion
+- `catch (err: Error)` -> `catch (err)`
+- `type T = typeof Foo` -> use the explicit type you need instead of a type query
+
+Reference:
+- Linter summary: declaration, operator, and statement sections